CentOS7.9下Pushgateway保姆级安装教程（附Prometheus 2.5.0配置）

从零到一：在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 常见问题与排查指南

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

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