ekofr/pihole-exporter

PI-Hole Prometheus Exporter 镜像文档

镜像概述

PI-Hole Prometheus Exporter是一款专为PI-Hole树莓派广告拦截器设计的Prometheus导出器。它能够从PI-Hole实例中采集关键运行指标（如拦截域名数量、DNS查询总量、广告拦截率等），并通过Prometheus兼容的接口暴露，支持与Grafana集成实现数据可视化监控。

核心功能与特性

• 全面指标采集：收集PI-Hole核心指标，包括拦截域名数、DNS查询量、广告拦截数、缓存查询数、客户端数量等
• 灵活配置：通过环境变量配置PI-Hole连接参数、数据拉取间隔及监听端口
• 可视化支持：提供官方Grafana仪表盘模板，一键导入即可实现监控数据可视化
• 轻量部署：基于Docker容器化构建，易于集成到现有Prometheus监控体系

使用场景与适用范围

适用于已部署PI-Hole广告拦截器的用户，需要对PI-Hole运行状态、广告拦截效果、网络查询性能进行实时监控和数据分析的场景。特别适合在Prometheus+Grafana监控架构中使用，帮助管理员直观掌握网络广告拦截情况。

详细使用方法

Docker部署示例

基础运行命令

通过以下命令启动容器，使用环境变量配置连接参数：

bash
docker run \
  -e 'PIHOLE_HOSTNAME=192.168.1.2' \  # PI-Hole主机IP或域名
  -e 'PIHOLE_PASSWORD=mypassword' \    # PI-Hole Web界面密码（二选一）
  # 或使用PI-Hole API令牌（从/etc/pihole/setupVars.conf的WEBPASSWORD获取）
  # -e 'PIHOLE_API_TOKEN=your_api_token' \
  -e 'INTERVAL=30s' \                  # 指标拉取间隔（默认10s）
  -e 'PORT=9617' \                     # 导出器监听端口（默认9617）
  -p 9617:9617 \                       # 端口映射
  ekofr/pihole-exporter:latest

HTTPS环境配置

若PI-Hole启用HTTPS访问，需添加协议配置并挂载SSL证书：

bash
docker run \
  -e 'PIHOLE_PROTOCOL=https' \         # 访问协议（http/https）
  -e 'PIHOLE_HOSTNAME=192.168.1.2' \
  -e 'PIHOLE_PASSWORD=mypassword' \
  -e 'INTERVAL=30s' \
  -e 'PORT=9617' \
  -v '/etc/ssl/certs:/etc/ssl/certs:ro' \  # 挂载本地SSL证书目录
  -p 9617:9617 \
  ekofr/pihole-exporter:latest

配置参数说明

Prometheus配置

在Prometheus配置文件prometheus.yml中添加如下抓取配置：

yaml
scrape_configs:
  - job_name: 'pihole'
    static_configs:
      - targets: ['<exporter_ip>:9617']  # 替换为导出器所在主机IP

Grafana仪表盘

提供官方预配置Grafana仪表盘模板，可通过以下链接获取：

• Grafana官网：[***]
• GitHub仓库：https://raw.githubusercontent.com/eko/pihole-exporter/master/grafana/dashboard.json

可用Prometheus指标

Kubernetes部署

提供Helm Chart用于Kubernetes集群部署，详情参见：https://github.com/SiM22/pihole-exporter-helm-chart