Pushgateway Docker镜像文档

一、镜像概述和主要用途

Pushgateway 是 Prometheus 生态系统中的核心组件之一，用于接收并持久化存储短生命周期作业（如批处理任务、定时任务）或临时服务发送的监控指标，并将这些指标以 Prometheus 可抓取的格式暴露，供 Prometheus 服务器定期采集。其核心价值在于解决 Prometheus 基于"拉取"（Pull）模式无法有效监控短生命周期任务的问题，通过"推送"（Push）模式补充指标采集能力。

二、核心功能和特性

2.1 核心功能

• 指标接收：支持通过 HTTP API 接收来自客户端的 Prometheus 格式指标（文本协议）。
• 指标存储：在内存中缓存指标，并可配置持久化到本地文件，避免容器重启导致指标丢失。
• 指标暴露：提供 HTTP 接口（默认 /metrics），供 Prometheus 服务器抓取指标数据。
• 多维度标签支持：允许指标携带 job、instance 及自定义标签，支持指标分组和聚合。

2.2 关键特性

• 轻量级设计：无外部依赖，单二进制文件，容器镜像体积小（约 20-30MB）。
• 持久化机制：可配置定期将内存中的指标持久化到文件，支持容器重启后恢复数据。
• 可扩展接口：支持自定义认证、TLS 加密（通过配置文件），满足生产环境安全需求。
• Prometheus 原生兼容：指标格式、标签规范完全符合 Prometheus 标准，无缝集成。

三、使用场景和适用范围

3.1 典型使用场景

• 短生命周期批处理任务：如定时数据清洗、报表生成等一次性任务，任务结束前推送执行状态/结果指标。
• 临时服务/作业：如 CI/CD 流水线任务、临时启动的脚本，生命周期短，Prometheus 无法主动发现和抓取。
• 边缘设备/嵌入式系统：网络环境受限或无法被 Prometheus 直接访问的设备，主动推送指标到中心节点。
• 多源指标聚合：接收来自多个分布式节点的同类指标，统一暴露给 Prometheus 抓取，简化监控配置。

3.2 不适用场景

• 长期运行服务的指标采集：此类服务建议直接暴露 /metrics 接口，由 Prometheus 主动拉取（更符合 Prometheus 设计理念）。
• 高并发指标推送：Pushgateway 设计目标为补充拉取模式，不适合高频、高吞吐的指标推送场景（可能导致性能瓶颈）。

四、使用方法和配置说明

4.1 获取镜像

Pushgateway 官方 Docker 镜像托管于 Docker Hub，可通过以下命令拉取最新版本：

docker pull prom/pushgateway:latest

也可指定具体版本（如 v1.6.2）：

docker pull prom/pushgateway:v1.6.2

4.2 基本使用（docker run）

4.2.1 最简启动

启动一个基础 Pushgateway 容器，暴露默认端口（9091）：

docker run -d \
  --name pushgateway \
  -p 9091:9091 \
  prom/pushgateway:latest

• 容器启动后，可通过 http://<主机IP>:9091 访问 Web UI，通过 http://<主机IP>:9091/metrics 查看暴露的指标。

4.2.2 带持久化配置

为避免容器重启后指标丢失，需配置持久化文件并挂载本地目录：

docker run -d \
  --name pushgateway \
  -p 9091:9091 \
  -v /path/on/host/pushgateway-data:/data \  # 本地目录挂载到容器内 /data
  prom/pushgateway:latest \
  --persistence.file=/data/pushgateway.db \  # 指定持久化文件路径
  --persistence.interval=2m  # 每 2 分钟持久化一次（默认 5m）

4.3 Docker Compose 配置示例

适用于多容器协同场景（如与 Prometheus、Grafana 组成监控栈）：

version: '3'
services:
  pushgateway:
    image: prom/pushgateway:latest
    container_name: pushgateway
    restart: always
    ports:
      - "9091:9091"
    volumes:
      - ./pushgateway-data:/data  # 本地持久化目录
    command:
      - --persistence.file=/data/pushgateway.db
      - --persistence.interval=2m
      - --web.listen-address=:9091  # 监听地址和端口（默认 :9091）
    networks:
      - monitoring-network  # 与 Prometheus 共享网络，避免端口暴露到宿主机

networks:
  monitoring-network:
    driver: bridge

4.4 向 Pushgateway 推送指标

客户端可通过 HTTP POST 请求向 Pushgateway 推送指标，格式为 Prometheus 文本协议。以下为常见推送方式示例：

4.4.1 基础推送（curl 命令）

推送一个简单指标 job_success{job="batch-processing"} 1（表示批处理任务成功）：

# 语法：POST /metrics/job/<job_name>/[instance/<instance_name>]
curl -X POST http://localhost:9091/metrics/job/batch-processing/instance/server-01 \
  --data-binary "job_success 1"

• <job_name>：必选，标识任务类型（如 batch-processing）。
• <instance_name>：可选，标识具体实例（如 server-01），用于区分同一 job 下的不同节点。

4.4.2 多指标批量推送

一次推送多个指标（换行分隔）：

cat <<EOF | curl -X POST http://localhost:9091/metrics/job/data-backup \
  --data-binary @-
backup_duration_seconds 120.5
backup_files_count 42
backup_success{status="ok"} 1
EOF

4.5 配置参数详解

Pushgateway 主要通过命令行参数配置，以下为常用参数说明：

4.5.1 Web 配置文件示例（TLS + 基本认证）

创建 web-config.yml 配置 TLS 和基本认证，挂载到容器并通过 --web.config.file 指定：

# web-config.yml
tls_config:
  cert_file: /etc/tls/cert.pem
  key_file: /etc/tls/key.pem
basic_auth_users:
  admin: $2a$10$xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # bcrypt 加密的密码（可通过 htpasswd 生成）

启动容器时挂载配置文件和 TLS 证书：

docker run -d \
  --name pushgateway \
  -p 9091:9091 \
  -v /path/on/host/web-config.yml:/etc/pushgateway/web-config.yml \
  -v /path/on/host/tls:/etc/tls \
  prom/pushgateway:latest \
  --web.config.file=/etc/pushgateway/web-config.yml

4.6 持久化数据

Pushgateway 内存中的指标默认不会持久化，容器重启后数据丢失。生产环境必须配置持久化：

1. 挂载宿主机目录到容器内目录（如 /data）。
2. 通过 --persistence.file 指定持久化文件路径（如 /data/pushgateway.db）。
3. （可选）通过 --persistence.interval 调整持久化频率（默认 5 分钟，高频推送场景可缩短间隔）。

五、Prometheus 配置抓取 Pushgateway 指标

在 Prometheus 配置文件 prometheus.yml 中添加以下 scrape_configs，抓取 Pushgateway 暴露的指标：

scrape_configs:
  - job_name: 'pushgateway'
    static_configs:
      - targets: ['pushgateway:9091']  # Pushgateway 容器名或 IP:端口（与 Prometheus 网络互通）
    honor_labels: true  # 保留指标原标签（避免 Pushgateway 自动添加的 instance 标签覆盖客户端标签）

• honor_labels: true 必须配置，否则 Prometheus 会用抓取目标的 instance 标签覆盖客户端推送的 instance 标签，导致指标混乱。

六、注意事项

1. 指标过期清理：Pushgateway 不会自动删除过期指标，需手动通过 API 删除（DELETE /metrics/job/<job_name>/[instance/<instance_name>]）或配置外部清理脚本。
2. 高可用：官方镜像不支持集群模式，生产环境需通过外部机制（如负载均衡 + 多实例）实现高可用，避免单点故障。
3. 安全性：公网环境务必启用 TLS 加密和认证（如基本认证、OAuth2），防止未授权访问或指标篡改。
4. 监控 Pushgateway 自身：建议同时监控 Pushgateway 自身指标（通过其 /metrics 接口），关注 pushgateway_http_requests_total（请求量）、pushgateway_storage_size_bytes（存储大小）等指标，及时发现异常。