从零到一：在CentOS 7.9上构建Pushgateway与Prometheus的监控数据枢纽

如果你正在搭建一套现代化的监控系统，Prometheus无疑是核心组件。但你是否遇到过这样的场景：一些短生命周期的任务、批处理作业，或者来自第三方系统的指标，无法被Prometheus主动拉取？这时，一个名为Pushgateway的“中转站”就显得至关重要。它允许你将数据主动推送给监控系统，完美填补了Prometheus拉取模型的空白。今天，我们就来深入探讨如何在经典的CentOS 7.9系统上，从零开始部署Pushgateway，并让它与Prometheus 2.5.0无缝协同工作。整个过程不仅仅是执行几条命令，更涉及对架构的理解、生产环境下的最佳实践，以及如何避开那些新手常踩的“坑”。

1. 理解Pushgateway：为什么需要它，以及它的正确使用姿势

在深入安装步骤之前，花点时间理解Pushgateway的设计哲学至关重要。Prometheus的核心设计是基于拉取（Pull）模型的：由Prometheus Server主动去各个被监控目标（Target）上抓取（Scrape）指标数据。这种模型在监控服务器、服务等长期运行的进程时非常高效和可靠。

然而，现实世界是复杂的。设想一下这些情况：

  • 一个运行仅5秒就结束的Cron定时任务，你需要知道它是否成功执行以及耗时。
  • 一个批处理数据分析作业，你想统计其处理的数据行数。
  • 来自AWS Lambda等无服务器函数（Serverless Function）的指标。
  • 一些遗留系统或第三方黑盒系统，它们无法暴露一个Prometheus能够访问的/metrics端点。

对于这些场景，让Prometheus去“拉取”数据要么不可能（任务已结束），要么不现实。Pushgateway应运而生，它作为一个指标缓存层和网关。短生命周期任务在结束前，将自身的指标推送到Pushgateway；Prometheus则像监控一个普通目标一样，定期从Pushgateway拉取这些缓存下来的指标。

注意：Pushgateway并非用于将所有指标都改为推送模式。 滥用Pushgateway会导致单点故障、数据过期等问题。它只应用于监控那些无法被拉取的作业（Jobs）或批处理任务（Batch Jobs）。

它的工作流程可以概括为：

  1. 推送：客户端应用（如脚本、批处理作业）通过HTTP API将指标数据POST到Pushgateway。
  2. 缓存：Pushgateway将接收到的指标存储在内存中。
  3. 拉取：Prometheus Server在配置的抓取周期内，访问Pushgateway的/metrics端点，获取所有已缓存的指标。
  4. 清理：Pushgateway本身不会主动删除数据。对于批处理任务，通常需要在任务成功后推送一次，失败后推送另一次（可能带有不同的指标值），并依赖后续任务推送来覆盖旧数据。对于需要清理的场景，可以通过API手动删除。

理解了这些，我们就能在正确的场景下使用它，避免架构上的误用。

2. 基础环境准备与Pushgateway的安装部署

我们假设你已经在CentOS 7.9上运行着一个Prometheus 2.5.0 Server。如果没有，你需要先完成它的安装，这通常是监控体系的起点。本节将专注于Pushgateway本身的部署。

2.1 系统环境检查与依赖确认

首先，登录到计划部署Pushgateway的服务器。这台服务器可以是独立的，也可以与Prometheus Server或其他应用部署在一起，根据你的资源规划和网络策略决定。

# 检查系统版本，确认是CentOS 7.9
cat /etc/redhat-release

# 检查防火墙状态，默认端口9091需要开放
systemctl status firewalld
# 如果防火墙开启，需要永久开放9091端口
sudo firewall-cmd --permanent --add-port=9091/tcp
sudo firewall-cmd --reload

# 确保有wget或curl工具用于下载
which wget curl

2.2 下载与安装Pushgateway

我们将从Prometheus官方GitHub仓库下载最新的稳定版本。请注意，版本号可能会更新，建议访问 Prometheus Pushgateway Releases 页面查看最新版本。

# 创建一个专用的系统用户来运行Pushgateway（安全最佳实践）
sudo useradd --no-create-home --shell /bin/false pushgateway

# 进入临时下载目录
cd /tmp

# 下载Pushgateway。这里以当时最新的稳定版v1.6.2为例，请替换为实际最新版本。
wget https://github.com/prometheus/pushgateway/releases/download/v1.6.2/pushgateway-1.6.2.linux-amd64.tar.gz

# 验证下载文件的完整性（可选但推荐）
wget https://github.com/prometheus/pushgateway/releases/download/v1.6.2/sha256sums.txt
sha256sum -c sha256sums.txt 2>/dev/null | grep pushgateway-1.6.2.linux-amd64.tar.gz

# 解压到系统目录
sudo tar -xvf pushgateway-1.6.2.linux-amd64.tar.gz -C /opt/

# 创建软链接，便于版本管理
sudo ln -s /opt/pushgateway-1.6.2.linux-amd64 /opt/pushgateway

# 将二进制文件所有权赋予pushgateway用户
sudo chown -R pushgateway:pushgateway /opt/pushgateway*

2.3 配置系统服务（Systemd）实现开机自启

使用Systemd管理服务是生产环境的标配，它能提供进程守护、日志管理、开机自启等功能。

创建服务配置文件：

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

将以下内容写入配置文件。这里我们添加了--web.listen-address=:9091参数来显式指定监听端口，虽然9091是默认值，但显式声明更清晰。--web.telemetry-path 保持默认的 /metrics 供Prometheus拉取。

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

[Service]
Type=simple
User=pushgateway
Group=pushgateway
ExecStart=/opt/pushgateway/pushgateway \
    --web.listen-address=:9091 \
    --web.telemetry-path=/metrics \
    --persistence.file=/var/lib/pushgateway/persist.file \
    --persistence.interval=5m
Restart=always
RestartSec=3

# 可选：设置资源限制
# LimitNOFILE=65536
# LimitNPROC=2048

# 数据持久化目录（防止重启后数据丢失）
ExecStartPre=/bin/mkdir -p /var/lib/pushgateway
ExecStartPre=/bin/chown -R pushgateway:pushgateway /var/lib/pushgateway

[Install]
WantedBy=multi-user.target

关键参数解析：

  • --persistence.file 和 --persistence.interval：这两个参数非常重要。它们会将Pushgateway内存中的指标定期（每5分钟）持久化到磁盘文件。这样，在Pushgateway服务重启后，之前推送的指标不会丢失。这对于监控批处理任务历史状态非常有用。
  • User/Group：使用非root用户运行，遵循最小权限原则。
  • Restart=always：确保进程意外退出后能自动重启。

现在，启动并启用服务：

# 重新加载systemd配置
sudo systemctl daemon-reload

# 启动Pushgateway服务
sudo systemctl start pushgateway

# 设置开机自启
sudo systemctl enable pushgateway

# 检查服务状态和日志
sudo systemctl status pushgateway
sudo journalctl -u pushgateway -f --lines=50

如果一切正常，你现在可以通过浏览器访问 http://<你的服务器IP>:9091。你会看到一个简洁的Web界面，目前“Metrics”下应该是空的，因为我们还没有推送任何数据。

3. 配置Prometheus Server抓取Pushgateway数据

Pushgateway已经就绪，但它只是一个“仓库”。我们需要告诉Prometheus Server这个“仓库”的位置，让它定期来“取货”。

3.1 修改Prometheus配置文件

找到你的Prometheus Server的配置文件 prometheus.yml。通常位于 /etc/prometheus/ 或你解压目录下。

在 scrape_configs 部分添加一个新的抓取任务（job）。这个job的目标（target）就是Pushgateway的地址。

scrape_configs:
  # 你原有的抓取配置，比如抓取Node Exporter的job
  - job_name: 'node_exporter'
    static_configs:
      - targets: ['192.168.1.101:9100', '192.168.1.102:9100']

  # 新增：专门用于抓取Pushgateway的job
  - job_name: 'pushgateway'
    honor_labels: true  # 这是一个关键配置！
    static_configs:
      - targets: ['192.168.1.100:9091'] # Pushgateway服务器的IP和端口
    # 可选：为从Pushgateway抓取的所有指标添加一个额外的标签，便于区分
    # metric_relabel_configs:
    #   - source_labels: [__address__]
    #     target_label: source
    #     replacement: 'pushgateway'

核心配置 honor_labels: true 详解： 这是配置中最容易出错也最重要的一点。在Prometheus的数据模型中，每个指标都有一组标签（label）来唯一标识它。当客户端向Pushgateway推送数据时，已经携带了完整的标签集（包括job和instance标签）。

  • 如果设置为 false（默认），Prometheus在抓取时，会用抓取配置中的job_name（这里是pushgateway）和targets中的地址（192.168.1.100:9091）去覆盖指标原有的job和instance标签。这会导致所有从Pushgateway来的指标，其job标签都变成pushgateway，从而无法区分原始的任务来源，失去了推送的意义。
  • 设置为 true 后，Prometheus会尊重并保留指标在推送时附带的原始标签。这样，一个由batch_job_A推送的指标，其job="batch_job_A"的标签会被保留，在Prometheus中能清晰地区分不同来源的指标。

3.2 重载Prometheus配置

修改配置后，需要让Prometheus重新加载配置，而无需重启服务。

# 方法1：向Prometheus发送SIGHUP信号（如果以前台进程运行）
# kill -HUP <prometheus_pid>

# 方法2：如果Prometheus通过systemd管理，且支持reload（通常配置了--web.enable-lifecycle）
# 首先检查Prometheus启动参数是否有 --web.enable-lifecycle
ps aux | grep prometheus

# 如果有，可以通过HTTP API触发重载
curl -X POST http://localhost:9090/-/reload

# 方法3：重启Prometheus服务（最直接，但有短暂中断）
sudo systemctl restart prometheus

配置生效后，访问你的Prometheus Web UI（默认http://<prometheus_ip>:9090），导航到 Status -> Targets。你应该能看到一个名为 pushgateway 的job，状态为 UP。

4. 实战：从脚本到仪表盘，完成一次完整的指标推送与可视化

理论配置已完成，现在是动手实践的时候。我们将通过一个具体的例子，演示如何编写脚本采集数据、推送到Pushgateway，并在Prometheus和Grafana中查看。

4.1 编写数据推送脚本

假设我们想监控服务器上处于 TIME_WAIT 状态的TCP连接数，这是一个常见的网络指标。我们创建一个Shell脚本。

#!/bin/bash
# 文件名：push_network_metrics.sh

# 1. 定义Pushgateway服务器地址
PUSHGATEWAY_URL="http://192.168.1.100:9091"

# 2. 定义Job名称和Instance标识。
# 通常，Job代表一类任务（如“batch_cleanup”），Instance代表具体运行实例（如主机名）。
# 对于主机监控，常用主机名作为instance，job可以命名为“custom_node_metrics”。
JOB_NAME="custom_node_metrics"
INSTANCE_NAME=$(hostname -f) # 使用完整主机名
# 如果主机名是localhost，建议使用IP地址
if [ "$INSTANCE_NAME" == "localhost" ]; then
    INSTANCE_NAME=$(hostname -I | awk '{print $1}')
fi

# 3. 采集指标数据
# 监控TIME_WAIT连接数
METRIC_NAME="node_network_tcp_time_wait"
TIME_WAIT_COUNT=$(ss -tan state time-wait | wc -l)

# 4. 构造推送数据
# Prometheus指标格式：<metric_name>{<label_name>=<label_value>, ...} <metric_value>
# 注意：指标值必须是数字（浮点数或整数）。
cat <<EOF | curl --data-binary @- ${PUSHGATEWAY_URL}/metrics/job/${JOB_NAME}/instance/${INSTANCE_NAME}
# TYPE ${METRIC_NAME} gauge
# HELP ${METRIC_NAME} Current number of TCP connections in TIME_WAIT state.
${METRIC_NAME} ${TIME_WAIT_COUNT}
EOF

# 5. 检查推送结果（可选）
if [ $? -eq 0 ]; then
    echo "$(date): 指标推送成功。"
else
    echo "$(date): 指标推送失败！" >&2
fi

脚本关键点解释：

  • --data-binary @-：curl 的这个参数表示从标准输入读取二进制数据并发送。@- 指从管道或heredoc中读取。
  • 推送URL路径：/metrics/job/<JOB_NAME>/instance/<INSTANCE_NAME>。这是Pushgateway的标准API路径，用于按job和instance分组指标。你还可以添加更多分组标签，如 /metrics/job/backup/instance/db01/mode/full。
  • # TYPE 和 # HELP 行：这些是Prometheus指标格式中的注释行，用于定义指标类型（gauge, counter, histogram, summary）和帮助信息，虽然不是强制要求，但强烈建议加上，能极大提高指标的可读性。
  • 指标类型选择：TIME_WAIT连接数是一个当前瞬时值，适合用 Gauge 类型。如果你的指标是累计计数（如任务执行总次数），则应使用 Counter 类型。

给脚本执行权限并手动测试：

chmod +x push_network_metrics.sh
./push_network_metrics.sh

执行后，立即刷新Pushgateway的Web界面(http://192.168.1.100:9091)，你应该能在Metrics页面下看到刚刚推送的 node_network_tcp_time_wait 指标。

4.2 配置定时任务与推送策略

对于需要持续监控的指标，我们需要设置定时任务（如Cron）。

# 编辑当前用户的crontab
crontab -e

添加一行，例如每分钟执行一次：

* * * * * /bin/bash /path/to/your/push_network_metrics.sh >> /var/log/pushgateway_metrics.log 2>&1

关于推送频率的思考：

  • 不要过度推送：Pushgateway不是为高频实时数据设计的。对于需要秒级监控的指标，应优先考虑让应用暴露标准的/metrics端点，由Prometheus直接拉取。
  • 批处理任务的推送时机：对于批处理任务，应在任务开始、结束（成功或失败）等关键节点推送指标。例如，推送一个 my_batch_job_last_success_timestamp 的Gauge指标，值为任务结束时的Unix时间戳。Prometheus抓取后，通过时间戳就能判断任务是否按时完成。

4.3 在Prometheus与Grafana中查询与展示

现在，数据已经通过Pushgateway流入Prometheus。

  1. 在Prometheus中查询： 打开Prometheus的Graph页面(http://<prometheus_ip>:9090/graph)。在查询框中输入 node_network_tcp_time_wait，执行查询。你应该能看到带有 job="custom_node_metrics" 和 instance="你的主机名" 标签的指标数据。你可以使用PromQL进行更复杂的查询，例如：

    # 查询所有实例的TIME_WAIT连接数
node_network_tcp_time_wait

# 查询特定实例最近5分钟的平均值
avg_over_time(node_network_tcp_time_wait{instance="your-hostname"}[5m])

  2. 在Grafana中创建仪表盘： 如果你使用Grafana进行可视化，添加一个Prometheus数据源（指向你的Prometheus Server）。然后新建一个面板，在Metrics查询中同样使用 node_network_tcp_time_wait。你可以为这个Gauge指标选择 Stat、Gauge 或 Graph 等多种展示形式，并设置合适的阈值告警（例如，当TIME_WAIT连接数超过10000时告警）。

5. 生产环境进阶考量与故障排查

将Pushgateway用于生产环境，还需要考虑更多因素。

5.1 安全性增强

默认配置下，Pushgateway的API没有认证，任何人都可以推送或删除数据，这存在风险。

  • 网络隔离：将Pushgateway部署在内网，仅允许特定的Prometheus Server和受信任的客户端IP段访问其端口（9091）。
  • 反向代理与认证：在Pushgateway前部署Nginx或Apache等反向代理，配置HTTP Basic认证或集成企业级单点登录（SSO）。
    # Nginx 配置示例片段
location / {
    proxy_pass http://localhost:9091;
    auth_basic "Pushgateway Admin";
    auth_basic_user_file /etc/nginx/.htpasswd;
    # 还可以限制允许的HTTP方法
    limit_except GET POST {
        deny all;
    }
}
  • 使用HTTPS：通过反向代理为Pushgateway启用HTTPS，加密传输数据。

5.2 性能、高可用与数据管理

  • 监控Pushgateway自身：Pushgateway暴露了自身的运行时指标（如 pushgateway_http_requests_total），记得让Prometheus也抓取这些指标，监控其健康状态和请求量。
  • 避免成为单点故障：对于关键业务，可以考虑部署多个Pushgateway实例，并在客户端实现简单的推送失败重试或负载均衡。但请注意，Prometheus侧的配置需要相应地将多个Pushgateway都列为target。
  • 数据清理：Pushgateway不会自动删除旧数据。对于已经完成的批处理任务，如果其指标不再需要，应通过API删除，避免数据堆积。
    # 删除特定job和instance的指标组
curl -X DELETE http://pushgateway.address:9091/metrics/job/my_job/instance/my_instance

# 删除整个job下的所有指标（慎用！）
curl -X DELETE http://pushgateway.address:9091/metrics/job/my_job
    可以考虑在批处理任务脚本的最后，成功执行后推送最终指标，然后延迟几秒后删除该任务对应的指标组。

5.3 常见问题与排查指南

遇到问题时，可以按照以下步骤排查：

问题现象可能原因排查步骤
Prometheus Target显示 DOWN网络不通、防火墙、Pushgateway服务未运行1. curl -v http://pushgateway_ip:9091/metrics 从Prometheus服务器测试连通性。
2. 检查双方防火墙规则。
3. systemctl status pushgateway 检查服务状态和日志。
Prometheus Target显示 UP，但查不到推送的指标1. honor_labels 未设置为 true。
2. 推送的指标格式错误。
3. 推送的URL路径（job/instance）与查询条件不匹配。		1. 确认 prometheus.yml 中 honor_labels: true。
2. 直接访问Pushgateway UI，查看指标是否已存在且格式正确。
3. 在Prometheus中使用 {job=~".*"} 查询所有job，检查你的指标标签是否正确。
推送脚本执行成功，但Pushgateway无数据脚本逻辑错误，采集的命令输出为空或非数字。1. 在脚本中增加调试输出，打印采集到的原始值。
2. 确保curl命令的URL拼接正确，特别是包含特殊字符时需要转义。
Pushgateway内存使用持续增长推送了大量指标且未清理，或者推送频率过高。1. 检查Pushgateway的指标数量 pushgateway_metrics_count。
2. 审查客户端推送逻辑，是否只推送必要数据，并对完成的任务进行清理。

最后，记得为你的Pushgateway和相关的推送脚本建立完善的监控和告警。监控其内存使用、HTTP错误率、指标数量等，确保这个数据中转站本身的稳定可靠。当你成功地将短生命周期任务、批处理作业的数据纳入统一的监控视野时，你会发现整个系统的可观测性又上了一个新的台阶。

Logo
乐奇 Rokid 开放社区

更多推荐

从对话到行动：用 AIUI 构建「喝水节奏教练」

「喝水节奏教练」是专为Rokid AI眼镜设计的本地化饮水记录智能体，通过自然语言指令实现“记一杯”“查进度”“撤销错误”等操作，数据全程本地存储。基于意图驱动的单页面UI，结合语音识别与A2UI动态渲染，支持快速记录、实时核对与修正，不依赖云端或健康数据，专注轻量可信的饮水节奏管理。

avatar 乐奇 Rokid 开放社区

智能眼镜市场全景解析：从技术演进到产业格局

本文系统梳理智能眼镜市场，涵盖产品形态、技术演进、市场规模、产业链结构及竞争格局。指出智能眼镜正从音频交互向AR显示与空间计算演进，受AI大模型、供应链成熟与生态延伸驱动，呈现分层发展态势。虽面临场景刚需不足、续航重量矛盾与隐私挑战，但B端应用先行、AI原生设计与标准完善将推动行业迈向规模化渗透，未来需关注核心技术突破与真实使用数据。

avatar 乐奇 Rokid 开放社区
cover

【日常逃跑计划：把世界戴在眼睛上，是什么体验？】

avatar 乐奇 Rokid 开放社区