Prometheus Pushgateway教程：离线任务指标上报、Shell与Python示例、远程访问

前言

Prometheus最擅长的是"主动去抓"长期运行服务的指标，但并不是所有任务都会一直在线。

比如每天凌晨跑一次的备份脚本、只执行几分钟的CI/CD任务、定时数据清洗或一次性批处理，这些任务结束以后进程就不存在了。等Prometheus下一次来抓时，任务早已经退出，自然也拿不到它刚才到底成功还是失败、执行了多久、处理了多少数据。

Pushgateway就是为这类短生命周期任务提供一个中间指标缓存点：任务结束前主动把结果推送到Pushgateway，Prometheus仍然保持原来的Pull模式，只不过改为定期抓取Pushgateway。

这篇文章完整跑一遍这条链：二进制和Docker两种方式部署Pushgateway → Prometheus配置抓取 → curl推送和删除指标 → Shell备份任务上报 → Python批处理上报 → 最后通过cpolar测试跨网络推送。

需要先说明，Pushgateway并不是把Prometheus整体改造成Push模式，也不适合拿来代替普通Exporter。它更适合有明确结束点的服务级批处理任务。

1.先明确Pushgateway适合什么场景

本文在Linux虚拟机中演示。原稿实际使用的版本与安装包如下：

Oracle VirtualBox: 5.1.20 r114628 (Qt5.6.2)

System: CentOS Linux release 7.9.2009 (Core)

Docker: 26.1.4

Prometheus: v3.5.0

Pushgateway: 1.11.2（与本文实际下载的二进制包一致）

版本说明 ：本文命令和截图基于Pushgateway 1.11.2。截至2026年10月，官方最新稳定版为1.11.3；如果你改用最新版下载包，请同步替换下面解压和重命名命令中的版本号。

本文默认已经有可用的Prometheus环境。如果还没有，可以先完成Prometheus部署，再继续配置Pushgateway。

2.安装Pushgateway

2.1 使用二进制包安装

先下载Linux对应的Pushgateway二进制包。本文原稿使用1.11.2：

选择Linux amd64版本：

下载完成后上传到/app目录。

然后解压：

shell 复制代码

tar -zxvf pushgateway-1.11.2.linux-amd64.tar.gz

为了后续路径更简单，将目录重命名为pushgateway，并删除压缩包：

shell 复制代码

mv pushgateway-1.11.2.linux-amd64 pushgateway
rm -rf pushgateway-1.11.2.linux-amd64.tar.gz

接着创建systemd服务文件：

shell 复制代码

sudo vim /etc/systemd/system/pushgateway.service

shell 复制代码

[Unit]
Description=Pushgateway for Prometheus
Documentation=https://github.com/prometheus/pushgateway
After=network-online.target

[Service]
Type=simple
User=prometheus
Group=prometheus
ExecStart=/app/pushgateway/pushgateway \
  --web.listen-address=:9091 \
  --web.enable-admin-api \
  --log.level=info
WorkingDirectory=/app/pushgateway
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal
SyslogIdentifier=pushgateway

[Install]
WantedBy=multi-user.target

按原稿把目录属主设为prometheus用户，并确保二进制可执行。注意：如果系统中没有prometheus用户，这一步以及后面的systemd服务会失败，需要先使用实际存在的运行用户。

持久化提醒 ：原稿这套启动参数没有配置--persistence.file。Pushgateway默认把推送指标保存在内存中，服务重启后这些指标不会自动恢复；如果你的场景要求重启后保留，需要再单独配置持久化文件。

shell 复制代码

sudo chown -R prometheus:prometheus /app/pushgateway
sudo chmod +x /app/pushgateway/pushgateway

重载systemd并启动Pushgateway：

shell 复制代码

# 重载配置
sudo systemctl daemon-reexec
sudo systemctl daemon-reload

# 启动并设置开机自启
sudo systemctl start pushgateway
sudo systemctl enable pushgateway

# 查看状态
sudo systemctl status pushgateway

再检查进程、指标端点和日志：

shell 复制代码

# 检查进程
ps aux | grep pushgateway

# 访问指标端点（本地）
curl http://localhost:9091/metrics

# 查看日志
journalctl -u pushgateway -f

如果需要从其他主机直接访问9091端口，再按需放行防火墙：

shell 复制代码

# CentOS 7 使用 firewalld
sudo firewall-cmd --permanent --add-port=9091/tcp
sudo firewall-cmd --reload

此时浏览器访问http://<ip>:9091即可进入Pushgateway UI。刚部署时还没有业务指标，因为还没有任务向它推送数据。

Pushgateway本身也会暴露Go、process等运行指标，可以通过http://<ip>:9091/metrics查看。

2.2 使用Docker安装

如果不想直接运行二进制，也可以使用官方prom/pushgateway镜像：

shell 复制代码

docker pull prom/pushgateway

然后启动容器并映射9091端口：

shell 复制代码

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

启动后访问：

shell 复制代码

http://ip:9091/

3.让Prometheus开始抓取Pushgateway

Pushgateway只是临时保存并暴露任务指标，最终仍然需要Prometheus主动抓取它。因此需要在prometheus.yml中增加一个scrape job。

打开Prometheus配置文件：

shell 复制代码

vi /app/prometheus/prometheus.yml

yaml 复制代码

  - job_name: 'pushgateway'
    honor_labels: true
    static_configs:
      - targets: ['localhost:9091']
        labels:
          app: "pushgateway"

保存配置后重启Prometheus：

shell 复制代码

systemctl restart prometheus
systemctl status prometheus

随后进入Prometheus的Targets页面，确认Pushgateway目标已经处于UP状态。

4.向Pushgateway推送和删除指标

Pushgateway提供HTTP API，短生命周期任务结束前可以主动把指标推送到对应的grouping key。

基本URL形式为：http://<ip>:9091/metrics/job/<JOBNAME>{/<LABEL_NAME>/<LABEL_VALUE>}。

JOBNAME是必填项，后面还可以继续增加其他标签。需要注意，Prometheus官方更推荐Pushgateway用于服务级批处理任务 ，这类指标不一定需要绑定具体机器或instance，否则后续还要自己处理过期实例指标。

先推送一个最简单的测试指标：

shell 复制代码

echo "test_metric 123456" | curl --data-binary @- http://192.168.42.140:9091/metrics/job/test_job

回到Pushgateway页面即可看到test_job。

除了业务指标，Pushgateway还会为每个group补充push_time_seconds和push_failure_time_seconds，用来表示最近一次成功/失败推送时间。

Prometheus完成下一次抓取后，就可以在查询页面看到这个指标。

如果确实需要区分来源实例，也可以在grouping key中增加instance：

shell 复制代码

cat <<EOF | curl --data-binary @- http://192.168.42.140:9091/metrics/job/some_job/instance/some_instance
# TYPE some_metric counter
some_metric{label="val1"} 42
# TYPE another_metric gauge
# HELP another_metric Just an example.
another_metric 2398.283
EOF

任务实例不再需要时，可以删除对应group中的数据：

复制代码

curl -X DELETE http://192.168.42.140:9091/metrics/job/some_job/instance/some_instance

也可以删除整个job分组：

复制代码

curl -X DELETE http://192.168.42.140:9091/metrics/job/some_job

5.两个真实任务示例

5.1 Shell备份任务：上报耗时和执行结果

下面模拟一个备份任务，在任务结束时把耗时和成功状态推送到Pushgateway，随后由Prometheus统一采集。

shell 复制代码

#!/bin/bash

JOB_NAME="daily_backup"
INSTANCE="server01"
PUSHGATEWAY_URL="http://localhost:9091"

start_time=$(date +%s)

# 模拟备份操作
echo "Starting backup..."
sleep 3
backup_success=1  # 1 表示成功，0 表示失败（实际可由命令返回值决定）

end_time=$(date +%s)
duration=$((end_time - start_time))

# 构建指标
cat <<EOF | curl --data-binary @- http://localhost:9091/metrics/job/$JOB_NAME/instance/$INSTANCE
# HELP backup_duration_seconds Duration of the backup job in seconds
# TYPE backup_duration_seconds gauge
backup_duration_seconds $duration

# HELP backup_success Whether the backup succeeded (1) or failed (0)
# TYPE backup_success gauge
backup_success $backup_success
EOF

echo "Metrics pushed to Pushgateway."

执行后进入http://ip:9091即可看到对应指标分组：

Prometheus抓取后，可以查询到类似指标：

shell 复制代码

backup_duration_seconds{job="daily_backup", instance="server01"} 3
backup_success{job="daily_backup", instance="server01"} 1

5.2 Python批处理：上报处理条数和成功状态

第二个例子模拟一次Python数据处理任务，在任务结束时上报处理记录数和成功状态。

shell 复制代码

import requests
import time

def push_metrics(job, instance, records_processed, success):
    metrics = f"""
    # HELP data_records_processed Number of records processed
    # TYPE data_records_processed gauge
    data_records_processed {records_processed}

    # HELP data_job_success Job success status (1 = success, 0 = failure)
    # TYPE data_job_success gauge
    data_job_success {int(success)}
    """
    url = f"http://localhost:9091/metrics/job/{job}/instance/{instance}"
    response = requests.post(url, data=metrics.encode('utf-8'))
    if response.status_code in (200, 202):
        print("Metrics pushed successfully.")
    else:
        print(f"Failed to push metrics: {response.status_code} - {response.text}")

# 模拟任务
start = time.time()
try:
    # 模拟处理 1500 条数据
    records = 1500
    time.sleep(2)
    success = True
except Exception as e:
    records = 0
    success = False

push_metrics(
    job="data_pipeline",
    instance="worker-node-01",
    records_processed=records,
    success=success
)

运行脚本：

shell 复制代码

python3 1.py

执行后进入http://ip:9091即可看到对应指标分组：

Prometheus完成抓取后，可以查询到：

shell 复制代码

data_records_processed{job="data_pipeline", instance="worker-node-01"} 1500
data_job_success{job="data_pipeline", instance="worker-node-01"} 1

如果CI/CD流水线、云主机或异地脚本无法直接访问内网中的Pushgateway，还需要解决网络可达性。下面原稿使用cpolar给9091端口增加公网入口，让外部任务能够访问Pushgateway的推送API。这里要特别注意：Pushgateway的HTTP接口不仅能查看指标，还能写入和删除指标，公网开放时必须额外做好认证和访问控制，不能把一个无保护的9091接口长期暴露在公网。