Alertmanager Docker Compose 部署指南

目标：使用 Docker Compose 在 Ubuntu 24.04 服务器上单容器部署 Alertmanager 0.34.1，覆盖 compose 文件、数据卷持久化、参数覆盖、运维命令与排障。所有命令与回显均来自真实服务器（服务器内 Docker 29.8.1 + Compose v5.5.1）实测。

一、环境信息

信息项	值
操作系统	Ubuntu 24.04 LTS
Docker	29.8.1
Docker Compose	v5.5.1
镜像	prom/alertmanager:v0.34.1
容器名	alertmanager
服务端口	9093（Web UI/API，映射宿主机 9093）
数据卷	alertmanager-data（命名卷，挂载到容器 /alertmanager）
配置文件	./alertmanager.yml（bind 挂载到 /etc/alertmanager/alertmanager.yml）

二、镜像选型说明

镜像	说明
prom/alertmanager:v0.34.1	官方镜像，与二进制版本一一对应，含 amtool 与默认配置，推荐
prom/alertmanager:latest	跟随最新版，版本不可控，生产不建议

💡 说明：官方镜像的入口为 /bin/alertmanager，镜像内同时提供 amtool，可用 docker compose exec 直接执行 amtool 管理告警。

三、前置条件

服务器已安装 Docker 与 Docker Compose 插件（docker compose version 验证）
部署目录 /opt/alertmanager-compose 已创建
可拉取 Docker Hub 镜像（内网环境需提前 docker pull prom/alertmanager:v0.34.1 导入）

四、部署步骤

4.1 创建部署目录与配置文件

mkdir -p /opt/alertmanager-compose
cd /opt/alertmanager-compose

编写 Alertmanager 配置 alertmanager.yml：

route:
  group_by: ["alertname"]
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 1h
  receiver: "web.hook"
receivers:
  - name: "web.hook"
    webhook_configs:
      - url: "http://127.0.0.1:5001/"

4.2 编写 docker-compose.yml

services:
  alertmanager:
    image: prom/alertmanager:v0.34.1
    container_name: alertmanager
    restart: unless-stopped
    ports:
      - "9093:9093"
    volumes:
      - ./alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro
      - alertmanager-data:/alertmanager
    command:
      - --config.file=/etc/alertmanager/alertmanager.yml
      - --storage.path=/alertmanager
      - --web.listen-address=:9093

volumes:
  alertmanager-data:

💡 说明：command 显式指定三个核心参数：配置文件路径、数据目录（落到命名卷）、监听地址。./alertmanager.yml 只读挂载，容器内不可篡改配置。

4.3 启动服务

docker compose up -d
docker compose ps

实测回显：

 Container alertmanager Starting
 Container alertmanager Started
NAME           IMAGE                       COMMAND                  SERVICE        CREATED         STATUS         PORTS
alertmanager   prom/alertmanager:v0.34.1   "/bin/alertmanager -…"   alertmanager   9 seconds ago   Up 6 seconds   0.0.0.0:9093->9093/tcp, [::]:9093->9093/tcp

4.4 验证服务

curl -s http://127.0.0.1:9093/-/healthy
docker compose exec alertmanager alertmanager --version

实测回显：

OK
alertmanager, version 0.34.1 (branch: HEAD, revision: 73c6bfe7393929211294c1954f30d8ed78e4d0ad)

五、数据持久化说明

命名卷 alertmanager-data 挂载到容器内 /alertmanager（--storage.path 指向此处），存放 silences（静默）与通知日志（nflog），这两类数据跨容器重启保留。
告警本身是内存态：容器重启后未通知过的告警会丢失，需由上游 Prometheus 重新推送（属正常行为，与二进制部署一致）。
实测：创建静默后 docker compose restart alertmanager，静默仍在（回显见「十、常用运维命令」末）。

docker volume ls | grep alertmanager

实测回显：

local     alertmanager-compose_alertmanager-data

六、常用环境变量表

Alertmanager 官方镜像支持以 PREFIX_ 环境变量覆盖全部命令行参数（-- 转 _、- 转 _、前缀 PREFIX_），例如 --web.listen-address → PREFIX_WEB_LISTEN_ADDRESS。可在 compose 中注入：

    environment:
      - PREFIX_WEB_LISTEN_ADDRESS=:9095
      - PREFIX_DATA_RETENTION=168h
      - PREFIX_LOG_LEVEL=debug

💡 说明：环境变量方式与 command 二选一即可，command 优先级更高且更直观，本文推荐 command。

七、常用配置参数说明（command）

参数	默认值	说明
`--config.file`	alertmanager.yml	配置文件路径
`--storage.path`	data/	数据目录（静默/通知日志落盘处）
`--web.listen-address`	:9093	Web UI 与 API 监听地址，可重复声明多地址
`--data.retention`	120h	静默与通知日志保留时长
`--cluster.listen-address`	0.0.0.0:9094	gossip 集群监听；置空字符串 `""` 可关闭 HA 模式
`--log.level`	info	日志级别：debug/info/warn/error
`--web.external-url`	自动推导	反向代理场景下的外部访问地址

⚠️ 注意：若以 root 运行容器且数据卷权限异常，启动会报权限错误；此时在 command 中追加 --web.listen-address 等参数无效，应先检查卷属主（见 FAQ）。

八、配置文件持久化（conf 挂载）

配置文件经 ./alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro 挂载，宿主机改配置后执行 docker compose restart alertmanager 生效（官方镜像不含 SIGHUP 便捷入口，重启最直接）。
需要热加载时执行：

docker compose kill -s HUP alertmanager

💡 说明：热加载只重读配置文件不丢告警；改完建议先在本机用 amtool check-config 校验再重载。

九、等价 docker run 运行方式

docker run -d --name alertmanager \
  --restart unless-stopped \
  -p 9093:9093 \
  -v /opt/alertmanager-compose/alertmanager.yml:/etc/alertmanager/alertmanager.yml:ro \
  -v alertmanager-data:/alertmanager \
  prom/alertmanager:v0.34.1 \
  --config.file=/etc/alertmanager/alertmanager.yml \
  --storage.path=/alertmanager \
  --web.listen-address=:9093

十、常用运维命令

# 查看容器状态与日志
docker compose ps
docker compose logs -f alertmanager

# 重启 / 停止 / 启动
docker compose restart alertmanager
docker compose stop alertmanager
docker compose start alertmanager

# 进入容器执行 amtool（配置校验、告警查询、静默管理）
docker compose exec alertmanager amtool --alertmanager.url=http://127.0.0.1:9093 alert query
docker compose exec alertmanager amtool check-config /etc/alertmanager/alertmanager.yml

# 查看数据卷实际挂载点
docker volume inspect alertmanager-compose_alertmanager-data

# 停止并移除容器（卷保留）
docker compose down

实测 docker compose restart 后静默仍在：

=== 重启前创建静默 ===
243206c9-04aa-42f0-bde4-4cfe39c69635
=== restart 后查询 ===
ID                                    Matchers                 Ends At                  Created By  Comment
243206c9-04aa-42f0-bde4-4cfe39c69635  alertname="ComposeTest"  2026-10-08 22:19:27 UTC  admin       Compose 持久化验证

十一、常见问题（FAQ）

1. docker compose up -d 报 failed to mount ... overlay ... invalid argument？

内层/嵌套容器环境下 overlay 存储驱动不可用。将 Docker daemon 存储驱动切换为 vfs：dockerd --storage-driver=vfs 后重试（物理机正常环境无需处理）。

2. 9093 端口被占用？

改 ports 映射（如 "19093:9093"）并同步修改验证命令的端口。

3. 容器内时间与通知时间不符？

时区未注入。compose 中加 environment: TZ=Asia/Shanghai 后重启。

4. 配置修改不生效？

确认挂载的是宿主文件而非容器副本：docker compose exec alertmanager cat /etc/alertmanager/alertmanager.yml 核对；改后 docker compose restart。

5. 数据卷误删后如何恢复？

docker compose down -v 会连卷删除，静默与通知日志不可恢复；生产环境建议定期备份命名卷（docker run --rm -v alertmanager-data:/data -v /backup:/backup alpine tar czf /backup/am-data.tgz -C /data .）。

十二、参考链接

官方镜像仓库：https://hub.docker.com/r/prom/alertmanager
Alertmanager 配置文档：https://prometheus.io/docs/alerting/latest/configuration/
二进制部署见《Ubuntu 22.04 安装 Alertmanager 指南》，参数详见《Alertmanager 配置参数详解》