pihole-exporter：Pi-hole 监控指标导出器

项目简介

pihole-exporter 是一个用 Go 编写的 Prometheus exporter，用来把 Pi-hole（树莓派上的广告拦截 DNS 服务）的数据转换成 Prometheus 可抓取的指标。配合 Prometheus 与 Grafana，即可在面板中查看 Pi-hole 的运行情况。

项目同时提供可用的 Grafana 面板：Prometheus 版（Grafana Labs 面板 ID 10176）与 InfluxDB 2 (Flux) 版（ID 17094），面板 JSON 和预览图都放在仓库中。

主要功能

• 将 Pi-hole 数据导出为 Prometheus 指标，默认监听 9617 端口，指标路径为 /metrics
• 单个 exporter 实例可以同时监控多个 Pi-hole：主机名、协议、端口、密码/API Token 均可用逗号分隔成列表；所有实例共用同一个 /metrics 端点，每条序列带 hostname 标签，Prometheus 只需抓取一次
• 所有参数都能用同名大写环境变量代替（如 -pihole_hostname 对应 PIHOLE_HOSTNAME）
• 支持用 PIHOLE_PASSWORD_FILE 从文件（例如 Docker/Kubernetes secret）读取密码
• 支持通过 HTTPS 访问 Pi-hole，公共 CA 证书开箱可用
• 日志级别可配置（debug/info/warn/error），并提供 -healthcheck 用于容器健康检查
• 提供多架构二进制文件与 Docker 镜像

安装与使用

可直接下载对应架构的二进制（i386 / amd64 / arm64 / arm，附 .sha256.txt 校验文件），或使用 Docker 镜像：

docker run \
  -e 'PIHOLE_HOSTNAME=192.168.1.2' \
  -e 'PIHOLE_PASSWORD=mypassword' \
  -e 'PORT=9617' \
  -p 9617:9617 \
  ekofr/pihole-exporter:latest

PIHOLE_PASSWORD 可以是 Pi-hole 后台登录密码，也可以是后台 Settings > Web interface / API 中生成的应用密码。

从源码安装：

go install github.com/eko/pihole-exporter@latest

直接运行二进制：

./pihole_exporter -pihole_hostname 192.168.1.10 -pihole_password azerty

exporter 运行起来后，在 prometheus.yml 中加入抓取任务：

scrape_configs:
    - job_name: "pihole"
      static_configs:
          - targets: ["localhost:9617"]

使用 Grafana Alloy 时，可添加 prometheus.scrape 组件并转发给 prometheus.remote_write 组件。

常用参数（完整列表见 README）：-pihole_hostname、-pihole_protocol、-pihole_port、-pihole_password、-pihole_password_file、-timeout、-bind_addr、-port、-skip_tls_verification、-log_level、-debug、-version、-healthcheck。

注意事项

• 容器以非 root 用户（UID/GID 65532）运行，挂载进容器的密码文件必须对该用户可读
• PIHOLE_PASSWORD_FILE 不能与已设置内容的 PIHOLE_PASSWORD 同时使用
• 自签名证书可用 SKIP_TLS_VERIFICATION=true 跳过校验，但不要在不可信网络中使用
• Kubernetes 中若同命名空间存在名为 pihole 的 Service，会注入形如 tcp://10.0.0.1:80 的 PIHOLE_PORT，exporter 无法解析，需显式设置 PIHOLE_PORT 或配置 enableServiceLinks: false
• exporter 与 Pi-hole 处于同一 Docker 网络时，PIHOLE_HOSTNAME 填 Pi-hole 容器名，PIHOLE_PORT 填容器内监听端口（默认 80），而非宿主机映射端口
• 镜像内没有 shell 和 wget，健康检查直接用 exporter 自身的 -healthcheck
• 社区另外维护了 Helm chart，可用于 Kubernetes 部署

---

本作品整理自 GitHub 开源项目 eko/pihole-exporter，原作者 @eko，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。