Alertmanager 常用 CLI 命令与工具详解

目标：实测详解 Alertmanager 0.34.1 的两大工具——amtool（配置校验/告警查询/静默管理/路由测试/模板渲染）与 alertmanager 服务端启动参数（含真实默认值），并给出 HTTP API 对照。所有输出均来自 0.34.1 真实服务器实测（服务监听 9093，amtool 与 server 同版本）。

一、环境信息

信息项	值
Alertmanager / amtool 版本	0.34.1
amtool 位置	/usr/local/bin/amtool
server 位置	/usr/local/bin/alertmanager
服务地址	http://127.0.0.1:9093
amtool 配置路径	$HOME/.config/amtool/config.yml 或 /etc/amtool/config.yml（可选）

二、工具概览

amtool：运维日常主力，管理告警、静默、配置与集群。子命令：alert（query/add）、silence（add/query/update/expire/import）、check-config、config（show/routes）、cluster show、template render。
alertmanager：服务端二进制，本身只提供 --help/--version，全部能力经 HTTP API 暴露（Web UI 同源）。

amtool 完整子命令列表（实测 amtool 无参输出）：

Commands:
  help [<command>...]
  alert
    query* [<flags>] [<matcher-groups>...]
    add [<flags>] [<labels>...]
  silence
    add [<flags>] [<matcher-groups>...]
    expire [<silence-ids>...]
    import [<flags>] [<input-file>]
    query* [<flags>] [<matcher-groups>...]
    update [<flags>] [<update-ids>...]
  check-config [<check-files>...]
  cluster
    show*
  config
    show*
    routes [<flags>]
      show*
      test [<flags>] [<labels>...]
  template
    render --template.glob=TEMPLATE.GLOB --template.text=TEMPLATE.TEXT [<flags>]

三、前置条件

已部署 Alertmanager（见《Ubuntu 22.04 安装 Alertmanager 指南》）
每个 amtool 命令均需指定 --alertmanager.url=http://127.0.0.1:9093（或写入 amtool 配置文件免带）
已安装 curl（用于 HTTP API 对照）

四、alert 子命令：告警查询与注入

4.1 查询告警

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

实测回显：

Alertname  Starts At                Summary  State
TestAlert  2026-10-08 21:03:39 UTC  测试告警     active

扩展输出（含全部标签/注解/时间范围）：

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

JSON 输出（脚本处理用）：

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

💡 说明：State 列取值 active（正常通知）/suppressed（被抑制或静默）。默认只查 active+未处理告警，alert query 支持按 matcher 过滤（如 alert query severity=critical）。

4.2 注入告警（测试用）

amtool --alertmanager.url=http://127.0.0.1:9093 alert add alertname=TestAlert severity=critical instance=web-01 --annotation=summary="测试告警"

参数为 label=value 键值对；alertname 可省略写成 amtool alert add TestAlert。
注解用 --annotation=key=value，可多次指定。

⚠️ 实测坑：值含空格或特殊字符必须整体加引号：--annotation="summary=磁盘使用率 90%"。未加引号会报 unexpected 90%: expected a comma or close brace 并回退经典解析器。

五、silence 子命令：静默管理

5.1 新建静默

amtool --alertmanager.url=http://127.0.0.1:9093 silence add alertname=TestAlert --duration=10m --comment="维护窗口静默" --author=admin

实测回显（返回静默 UUID）：

92d8a24a-51de-468b-8f20-3c60babb5636

5.2 查询静默

amtool --alertmanager.url=http://127.0.0.1:9093 silence query

实测回显：

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

5.3 过期（提前解除）静默

amtool --alertmanager.url=http://127.0.0.1:9093 silence expire 92d8a24a-51de-468b-8f20-3c60babb5636

⚠️ 实测坑：expire 只接受静默 ID（query 第一列）。传 matcher 会报 [DELETE /silence/{silenceID}] deleteSilence (status 422)。

5.4 更新与批量导入

# 更新静默（延长时长等），参数同 add，需指定要更新的 ID
amtool --alertmanager.url=http://127.0.0.1:9093 silence update --help

# 从 query 导出的 JSON 批量导入（支持 stdin）
amtool --alertmanager.url=http://127.0.0.1:9093 silence query -o json > silences.json
amtool --alertmanager.url=http://127.0.0.1:9093 silence import silences.json

六、check-config：配置校验

amtool check-config /etc/alertmanager/alertmanager.yml

实测回显：

Checking '/etc/alertmanager/alertmanager.yml'  SUCCESS
Found:
 - global config
 - route
 - 1 inhibit rules
 - 1 receivers
 - 0 templates

💡 说明：返回 SUCCESS 且列出各配置块数量即合法；可一次传多个文件校验。

七、config 子命令：查看生效配置与路由测试

7.1 查看归一化后的完整配置

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

实测回显（节选）：

global:
  resolve_timeout: 5m
  http_config:
    follow_redirects: true
    enable_http2: true
  smtp_hello: localhost
  ...
route:
  receiver: echo
  group_by:
  - alertname
  continue: false
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 1h

7.2 路由树

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

实测回显：

Routing tree:
.
└── default-route  receiver: web.hook

7.3 路由测试（按标签预测走向）

amtool --alertmanager.url=http://127.0.0.1:9093 config routes test "alertname=DiskFull" "severity=warning"

实测回显：

echo

💡 说明：输出该组标签最终命中的 receiver 名。多个 matcher 必须分开传参，逗号拼在一个参数里会被当成单个值。

八、cluster show：集群状态

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

实测回显（单节点）：

Cluster Status:  ready
Node Name:       01M4ENB1X2P6D4TCKDCWFK58V6

九、template render：模板渲染验证

amtool template render --template.glob=/etc/alertmanager/tmpl/notify.tmpl --template.text="{{ .Receiver }} | {{ .Status }}" --alertmanager.url=http://127.0.0.1:9093

实测回显：

receiver | alertstatus

💡 说明：--template.glob 加载模板库，--template.text 为待渲染模板；输出即通知模板在该服务端环境下的渲染结果，用于上线前验证模板语法与字段引用。

十、alertmanager 服务端参数速查（实测默认值）

10.1 基本运行参数

参数	默认值	说明
`--config.file`	alertmanager.yml	配置文件路径
`--storage.path`	data/	数据目录
`--data.retention`	120h	静默/通知日志保留时长
`--data.maintenance-interval`	15m	GC 与落盘快照间隔
`--alerts.gc-interval`	30m	告警 GC 间隔
`--alerts.per-altername-limit`	0	每 alertname 告警上限（0 不限）
`--log.level`	info	debug/info/warn/error
`--log.format`	logfmt	logfmt/json

10.2 Web/API 参数

参数	默认值	说明
`--web.listen-address`	:9093	Web 与 API 监听地址（可重复）
`--web.external-url`	自动推导	反向代理场景外部地址
`--web.route-prefix`	同 external-url path	内部路由前缀
`--web.config.file`	空	TLS/认证配置（exporter-toolkit 格式）
`--web.get-concurrency`	0（=GOMAXPROC 或 8 取大）	GET 并发上限
`--web.timeout`	0（不限）	HTTP 请求超时

10.3 集群（HA）参数

参数	默认值	说明
`--cluster.listen-address`	0.0.0.0:9094	gossip 监听；置空关闭 HA
`--cluster.peer`	无	初始节点（可多次指定）
`--cluster.advertise-address`	自动	对外通告地址
`--cluster.gossip-interval`	200ms	gossip 消息发送间隔
`--cluster.pushpull-interval`	1m0s	全量状态同步间隔
`--cluster.probe-timeout`	500ms	节点探活超时
`--cluster.probe-interval`	1s	随机探测间隔
`--cluster.settle-timeout`	1m0s	通知前集群稳定等待上限
`--cluster.reconnect-interval`	10s	断线重连间隔
`--cluster.reconnect-timeout`	6h0m0s	重连总时长上限
`--cluster.peer-timeout`	15s	节点间通知等待超时
`--cluster.tcp-timeout`	10s	流式状态同步 TCP 超时
`--cluster.label`	空	集群标签，防跨集群串扰

10.4 其它参数

参数	默认值	说明
`--auto-gomemlimit.ratio`	0.9	自动内存上限比例（需 enable-feature）
`--silences.max-silences`	0	静默总数上限（0 不限）
`--silences.max-silence-size-bytes`	0	单条静默大小上限（0 不限）
`--enable-feature`	空	alert-names-in-metrics、classic-mode、utf8-strict-mode、auto-gomemlimit、event-recorder 等
`--web.systemd-socket`	false	使用 systemd socket 激活监听

十一、HTTP API 对照（常用）

端点	方法	用途
`/-/healthy`、`/-/ready`	GET	健康/就绪探活（返回 `OK`）
`/api/v2/status`	GET	集群状态+生效配置+版本
`/api/v2/alerts`	GET	查告警（`?inhibited=true` 含被抑制）
`/api/v2/alerts`	POST	推送告警（Prometheus/脚本用，JSON 数组）
`/api/v2/silences`	GET/POST	查/建静默
`/api/v2/silence/{id}`	GET/DELETE	查/删单条静默
`/-/reload`	POST	热加载配置（200 即成功）

实测：

curl -s http://127.0.0.1:9093/-/healthy
curl -s -X POST http://127.0.0.1:9093/-/reload

OK

十二、注意事项

amtool 与 alertmanager 版本必须匹配（同包发布），跨大版本可能出现协议不兼容。
生产账号密码不入命令：把 --alertmanager.url 等写进 /etc/amtool/config.yml 并限制权限 chmod 600。
告警注入命令仅用于测试，生产告警应来自 Prometheus 推送（POST /api/v2/alerts）。

十三、常见问题

1. amtool 提示 Post ...: EOF？

服务未就绪或端口不对。先 curl -s http://127.0.0.1:9093/-/ready，确认 OK 再执行。

2. alert query 查不到告警？

默认过滤未处理+active。加 -o json 看完整状态；被抑制/静默的告警 State 为 suppressed 且默认不显示，可在 Web UI 勾选显示。

3. 路由测试返回多个接收方？

config routes test 只输出最终命中 receiver；需查看完整决策链用 config routes 的树形输出人工比对。

十四、参考链接

amtool 官方手册：https://prometheus.io/docs/alerting/latest/amtool/
HTTP API：https://prometheus.io/docs/alerting/latest/clients/
各参数业务含义见《Alertmanager 配置参数详解》