PushProx 镜像文档

1. 概述

1.1 镜像概述和主要用途

Prometheus PushProx 是一个客户端-代理工具，旨在解决 Prometheus 无法直接访问位于 NAT 或其他隔离网络拓扑中目标的问题，同时保持 Prometheus 原生的拉取（pull）模型。该工具由代理（Proxy）和客户端（Client）两部分组成，通过代理中转实现 Prometheus 对隔离网络中目标的指标采集。

2. 核心功能与特性

• NAT 与网络隔离穿越：支持 Prometheus 监控位于 NAT 后或无法直接访问网络环境中的目标
• 保持拉取模型：不改变 Prometheus 基于拉取的设计哲学，符合其原生工作流
• 客户端自动注册：客户端主动向代理注册，无需手动配置目标节点
• 透明 HTTP 头传递：支持压缩、Accept-Encoding 等 HTTP 特性，由 Prometheus 控制
• 服务发现集成：提供 /clients 端点，返回符合 file_sd_configs 格式的客户端列表，支持动态发现

3. 使用场景与适用范围

• 跨 NAT 监控：目标主机位于家庭网络、边缘设备等 NAT 环境后，Prometheus 无法直接访问
• 隔离网络环境：目标位于防火墙隔离的网络分区，仅允许客户端主动连接外部代理
• 动态目标管理：需要自动发现并监控动态注册的客户端主机
• 原生拉取模型兼容：不适用于推送模式（如 Pushgateway），需保持 Prometheus 拉取机制的场景

4. 快速开始

4.1 前提条件

• Docker 环境（用于运行 PushProx 镜像）
• Prometheus 服务器（v2.0+ 推荐）
• 网络连通性：代理需同时被 Prometheus 和客户端访问，客户端需能连接代理

4.2 获取镜像

拉取官方 Docker 镜像：

docker pull prometheuscommunity/pushprox

4.3 运行代理（Proxy）

代理需部署在 Prometheus 和客户端均能访问的网络位置，默认监听 8080 端口。

Docker 运行命令：

docker run -d \
  --name pushprox-proxy \
  -p 8080:8080 \
  --restart unless-stopped \
  prometheuscommunity/pushprox proxy \
  --listen-address=:8080  # 可选，默认监听 :8080

4.4 运行客户端（Client）

客户端部署在目标主机上，需指向代理 URL，并可指定客户端标识、轮询间隔等参数。

基本 Docker 运行命令：

docker run -d \
  --name pushprox-client \
  --restart unless-stopped \
  prometheuscommunity/pushprox client \
  --proxy-url=[***] \  # 代理服务地址（必填）
  --fqdn=client-node-01.example.com \  # 可选，客户端标识（默认使用主机名）
  --poll-interval=10s \  # 可选，轮询代理间隔（默认 10s）
  --scrape-timeout=10s  # 可选，目标采集超时时间（默认 10s）

4.5 Prometheus 配置

在 Prometheus 配置中通过 proxy_url 指定 PushProx 代理，并配置目标节点。

示例配置（prometheus.yml）：

scrape_configs:
  - job_name: 'node-exporter-via-pushprox'
    proxy_url: '[***]  # 代理服务地址
    static_configs:
      - targets: ['client-node-01.example.com:9100']  # 客户端 FQDN 和目标端口（如 node-exporter 9100）
    
    # 若目标需通过 HTTPS 访问，添加以下参数（替代原生 scheme: https）
    params:
      _scheme: [https]

5. 服务发现

PushProx 代理提供 /clients 端点，返回所有已注册客户端的列表，格式符合 Prometheus file_sd_configs 要求，支持动态服务发现。

5.1 使用方法

1. 获取客户端列表：

   curl [***] > /etc/prometheus/pushprox-clients.json
   

2. 配置 Prometheus 动态发现：

   scrape_configs:
     - job_name: 'pushprox-dynamic-clients'
       proxy_url: '[***]
       file_sd_configs:
         - files: ['/etc/prometheus/pushprox-clients.json']  # 客户端列表文件
       relabel_configs:
         # 可选：添加 relabel 规则（如过滤、重命名标签等）
         - source_labels: [__meta_pushprox_fqdn]
           target_label: instance
   

3. 定期更新客户端列表：通过 cron 任务或监控工具定期执行 curl 命令，确保服务发现实时性。

6. 工作原理

6.1 基本流程

1. 客户端轮询代理：客户端以 FQDN 标识自身，定期向代理发送轮询请求，等待 Prometheus 的采集指令。
2. Prometheus 发起采集：Prometheus 通过代理的 proxy_url 向目标客户端（如 client-fqdn:9100）发起采集请求。
3. 代理路由请求：代理根据目标 FQDN 匹配对应的客户端，将采集请求通过轮询响应发送给客户端。
4. 客户端执行采集：客户端收到请求后，访问本地目标服务（如 node-exporter），获取指标数据。
5. 客户端返回结果：客户端将指标数据 POST 到代理。
6. 代理响应 Prometheus：代理将客户端返回的指标数据作为响应返回给 Prometheus。

7. 安全注意事项

• 无内置认证授权：PushProx 代理和客户端均未内置身份验证或授权机制，建议在代理前部署反向代理（如 Nginx、Traefik），添加 TLS、Basic Auth 或 OAuth2 等安全层。

• 客户端权限风险：运行客户端的主机可被通过代理访问其所有网络服务，需严格限制客户端主机的网络访问权限，避免未授权访问内部服务。

• 传输安全：建议通过 TLS 加密代理与客户端、Prometheus 与代理之间的通信，防止数据泄露或篡改。

8. 配置参数参考

8.1 代理（Proxy）参数

8.2 客户端（Client）参数