Alertmanager 安装与快速上手

上篇核心概念与架构讲清了 Alertmanager 的定位和五大机制，这篇动手把它跑起来：选部署方式、写一份最小 alertmanager.yml、让 Prometheus 连上、端到端发出第一条测试告警。环境口径：Alertmanager 0.27+，Prometheus 2.5x/3.x，Ubuntu 22.04 / Docker。

部署方式怎么选

Alertmanager 和 Prometheus 一样，是单个 Go 二进制、无外部依赖，三条路任选：

方式	适合场景	优点	缺点
二进制	裸机/虚机上的生产部署	透明直接，systemd 托管	安装、升级、服务单元都要手动
Docker	学习、本地验证、小环境	一条命令起，环境干净	配置文件和数据目录要挂载
Kubernetes	生产主力	operator 自动管理	要学 Helm / CRD 体系

K8s 上一般不手写 Deployment，直接用 kube-prometheus-stack（Helm Chart）——它内置了 Alertmanager，装完 Prometheus 就自带一个，配置通过 CRD 管理，那套体系本系列后面单独展开。学习阶段用 Docker 最快，本篇以 Docker 为主线，二进制顺带一提。

版本口径

本篇基于 Alertmanager 0.27+。0.27 起通知模板默认开启 UTF-8 严格解析、废弃了一批老的 API v1 行为，新部署直接用最新稳定版即可，不用纠结历史版本差异。

二进制与 Docker 跑起来

二进制方式：Alertmanager 和 Prometheus 在同一个官方下载页上，挑对应平台的压缩包：

官方下载页：prometheus.io/download（页面往下翻，alertmanager 一节）
GitHub Releases：prometheus/alertmanager/releases（版本更新最快）

# 以 linux-amd64 为例（macOS Apple Silicon 选 darwin-arm64）
curl -LO https://github.com/prometheus/alertmanager/releases/download/v0.28.1/alertmanager-0.28.1.linux-amd64.tar.gz

tar xf alertmanager-0.28.1.linux-amd64.tar.gz
cd alertmanager-0.28.1.linux-amd64
./alertmanager --config.file=alertmanager.yml

解压目录里自带一份 alertmanager.yml 示例配置，先跑通再改成自己的。

Docker 方式：先准备配置目录，把下一节的最小配置存进去，然后挂载启动：

# 准备配置目录
mkdir -p ~/alertmanager
# 把下面「最小 alertmanager.yml」存为 ~/alertmanager/alertmanager.yml

docker run -d \
  --name alertmanager \
  -p 9093:9093 \
  -v ~/alertmanager/alertmanager.yml:/etc/alertmanager/alertmanager.yml \
  -v ~/alertmanager/data:/alertmanager \
  prom/alertmanager:v0.28.1

参数说明：

-p 9093:9093：Web UI 和 API 都走 9093 端口。
第一个 -v：挂载配置文件到容器内的默认路径。
第二个 -v：挂载数据目录——nflog（通知日志）和静默列表存在这里，容器删了状态还在。

启动后浏览器打开 http://localhost:9093，能看到 Alertmanager 的 Web UI 就算成功。

改完配置热加载

和 Prometheus 一样，改完 alertmanager.yml 不用重启：docker kill --signal=SIGHUP alertmanager，或启动时加 --web.enable-lifecycle 后 curl -X POST http://localhost:9093/-/reload。注意 lifecycle 接口会同时开放远程关闭，别裸奔在公网。

最小 alertmanager.yml

Alertmanager 的配置就一个文件，核心三段：global（全局参数）、route（路由树）、receivers（接收器）。一份最小可用配置，逐行注释：

global:
  # 通知失败后的重试间隔等全局参数都在这段
  # 邮件类接收器需要的 smtp_* 参数也放这里，本例用 webhook 所以留空
  resolve_timeout: 5m          # 一条告警超过 5m 没再被推送，自动视为已恢复

route:
  receiver: default-webhook    # 根路由的默认接收器：所有告警没匹配到子路由都走它
  group_by: ["alertname"]      # 按告警名分组：同名告警合成一条通知
  group_wait: 10s              # 新告警组攒 10s 再首发，等同组告警凑齐
  group_interval: 1m           # 组内有新告警加入时，隔 1m 补发一次
  repeat_interval: 2h          # 告警一直没恢复时，隔 2h 重复提醒一次
  # routes:                    # 子路由：按标签把告警分发给不同接收器
  # 学习阶段先不配，所有告警走根路由的默认接收器

receivers:
  - name: default-webhook
    webhook_configs:
      - url: http://192.168.1.10:5001/webhook   # 换成你实际接收 webhook 的地址
        send_resolved: true                      # 恢复也发通知，端到端验证时需要

三个时间参数是新手最容易迷糊的，再强调一遍：

group_wait：通知「首发」前的等待。攒一攒同组告警，避免一条通知刚发出去又紧跟一条。
group_interval：组里已经发过通知后，组内新增告警的补发间隔。
repeat_interval：同一条告警一直没恢复时的重复提醒间隔。不是失败重试。

最小配置 ≠ 生产配置

这份配置只有一个兜底接收器、没有子路由、没有抑制规则，够验证链路，不够上生产。多团队路由、critical/warning 分级、inhibit_rules 怎么配，是本系列配置篇的内容。

让 Prometheus 连上

Alertmanager 起来之后，Prometheus 侧只需要在 prometheus.yml 里告诉它地址：

alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - "alertmanager:9093"    # 换成你的 Alertmanager 实际地址

改完热加载 Prometheus（kill -HUP 或 POST /-/reload），然后打开 Prometheus UI 的 Status → Runtime & Build Information（3.x）或 Status → Configuration（2.x），能看到 alertmanagers 配置生效；更直观的是 Alerts 页面告警触发后，Alertmanager 的 UI 上能同步看到。

多个实例的写法（高可用集群预告）：把集群里所有实例地址都列上即可，Prometheus 会把告警推给每一个：

alerting:
  alertmanagers:
    - static_configs:
        - targets:
            - "alertmanager-1:9093"
            - "alertmanager-2:9093"
            - "alertmanager-3:9093"

Alertmanager 集群内部靠 gossip 同步通知状态，保证推了三份只发一条通知。集群怎么搭是本系列高可用篇的内容，这里先把写法记住。

连接是 Prometheus 单向推

链路方向只有一个：Prometheus 推、Alertmanager 收。Alertmanager 从不反向连 Prometheus。排障时如果 Alertmanager UI 上看不到告警，问题一定在「Prometheus 没评估出 firing」或「推送没到达」，不用在 Alertmanager 侧找「抓取配置」。

端到端验证第一条告警

最快验证链路的方式：直接调 Alertmanager 的 API 手工塞一条告警，跳过 Prometheus 规则评估这一步，先确认 Alertmanager 到接收器这一段是通的。

先用 nc 起一个最简陋的 webhook 接收端（在配置里 url 指向的那台机器上）：

# 监听 5001 端口，收到请求打印内容（Ubuntu 22.04 自带 openbsd 版 nc）
nc -lk -p 5001

然后往 Alertmanager 塞一条 firing 告警：

curl -X POST http://localhost:9093/api/v2/alerts \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "labels": {
        "alertname": "TestAlert",
        "severity": "warning",
        "instance": "test-host:9100"
      },
      "annotations": {
        "summary": "这是一条手工触发的测试告警"
      },
      "startsAt": "2026-10-25T12:00:00Z",
      "generatorURL": "http://localhost:9090/graph"
    }
  ]'

预期的连锁反应：

curl 返回成功（{"status":"success"}）。
Alertmanager UI（http://localhost:9093）的 Alerts 列表里出现 TestAlert。
等 group_wait（10s）过后，nc 窗口里打印出 Alertmanager POST 过来的 JSON——分组后的告警数据。
过 5 分钟（resolve_timeout）没有新推送，这条告警自动转 resolved；因为配了 send_resolved: true，nc 会再收到一条 status 为 resolved 的通知。

到这一步，「告警进来 → 分组 → 路由 → 通知发出」的完整链路就验证通了。之后再接上 Prometheus 真实规则，只是把告警来源从手工 curl 换成规则评估，下游行为完全一致。

更好的 webhook 调试工具

nc 只能看个大概。想要格式化、可回溯的调试，用 webhook.site 这类在线工具（公网可达时），或者自己跑一个几十行的 HTTP echo 服务。生产上的 webhook 接收器（钉钉/企微转换层、自建告警网关）也是同样的姿势接住这个 JSON 再加工。

Web UI 与 amtool

Web UI（9093 端口）三个核心页面，日常运维够用：

Alerts：当前活跃告警列表，可按标签过滤，能看到每条告警的分组归属和静默状态。排障第一站：「告警到底到没到 Alertmanager」。
Silences：静默列表和创建入口。New Silence 填匹配器、起止时间、创建人、备注，比手写 API 请求直观。
Status：集群状态（gossip 成员列表）、当前加载的配置、运行参数。集群排障时看这里确认成员是否互相认到。

amtool 是官方命令行工具，二进制包里自带（Docker 镜像里也有）。两个最常用的姿势：

# 可视化查看当前生效的路由树——路由复杂后的排障神器
amtool config routes --config.file=alertmanager.yml

# 指定 Alertmanager 地址操作（创建静默、查告警等）
amtool --alertmanager.url=http://localhost:9093 silence add alertname=TestAlert \
  --duration=1h --comment="手工测试静默"

config routes 会把路由树画成缩进的文本结构，每个节点标着匹配条件和接收器，路由层级一深，YAML 里看不出告警最终落到哪个 receiver，这个命令一跑就清楚。

容器里用 amtool

Docker 部署时直接 docker exec -it alertmanager amtool ...，镜像里自带，不用另外装。

常见问题

端口冲突

9093 被占用时换宿主机映射端口即可，容器内不用动：

docker run -d --name alertmanager -p 19093:9093 -v ... prom/alertmanager:v0.28.1

注意改了宿主机端口后，Prometheus 的 alerting.alertmanagers targets 和 webhook 调试地址都要跟着改。

Prometheus 侧 alerting 配置不生效

最常见的症状：Alertmanager UI 上永远看不到告警。按顺序排查：

先看告警是不是真的 firing：打开 Prometheus UI 的 Alerts 页面，状态是 pending 就不会推送（for 没满），是 inactive 说明表达式根本不成立。九成「Alertmanager 没收到」的问题其实是规则没触发。
再看配置有没有加载：Prometheus 的 Status → Configuration 页面确认 alertmanagers 段存在且 targets 正确——改完 yml 忘记 reload 是高频翻车点。
最后看网络：Prometheus 容器里 curl http://alertmanager:9093/api/v2/status/cluster 试一下连通性。

容器网络互通

两个容器各用默认网桥时，Prometheus 容器里写 localhost:9093 指的是它自己，连不上 Alertmanager。两个解法：

同一自定义网络：docker network create monitor，两个容器都 --network monitor 启动，Prometheus 里直接写容器名 alertmanager:9093。
macOS / Windows（Docker Desktop）：指向宿主机上的 Alertmanager 时用内置域名 host.docker.internal:9093；Linux 上需要加 --add-host=host.docker.internal:host-gateway。

手工 POST 的告警马上消失了

/api/v2/alerts 收到的告警有个有效期：不带 endsAt 时按 resolve_timeout（默认 5m）自动过期转 resolved。这是设计如此——告警需要上游持续推送来「续命」，上游停了说明问题不在了。想维持测试告警存在，循环 POST 或者显式给一个未来的 endsAt。

小结

部署三选一：二进制透明、Docker 快、K8s 交给 kube-prometheus-stack；学习用 Docker 一条命令起步。
alertmanager.yml 三段结构：global 放全局参数、route 决定分组节奏和去向、receivers 定义通知渠道；三个时间参数 group_wait / group_interval / repeat_interval 各司其职。
Prometheus 侧只需 alerting.alertmanagers 配地址，单向推送；多实例把所有地址列上，去重交给集群。
端到端验证的最快路径：nc 起接收端 + curl /api/v2/alerts 塞一条测试告警，看 UI 出现、看通知到达。
UI 三页面：Alerts 看到没到、Silences 管静默、Status 看集群；amtool 的 config routes 可视化路由树。
排障口诀：先确认 Prometheus 侧真 firing，再确认配置已 reload，最后查网络连通。

跑通最小链路只是起点。下一篇进入配置深水区：路由树的多级匹配、通知模板怎么写人话、钉钉/企微转换层怎么接。

部署方式怎么选​

二进制与 Docker 跑起来​

最小 alertmanager.yml​

让 Prometheus 连上​

端到端验证第一条告警​

Web UI 与 amtool​

常见问题​

端口冲突​

Prometheus 侧 alerting 配置不生效​

容器网络互通​

手工 POST 的告警马上消失了​

小结​