Pi-Hole v6 仪表盘客户端数据缺失问题分析与解决方案

问题现象

在 Pi-Hole v6.0.4 版本中，部分用户反馈仪表盘中的"Top Clients"（顶级客户端）和"Client Activity"（客户端活动）数据框显示为空。该问题主要出现在通过 Nginx 反向代理访问 Pi-Hole 管理界面的场景下。

技术背景

Pi-Hole v6 采用了新的 API 架构设计，将管理界面和 API 服务分离。这种架构变化带来了以下技术特点：

1. 管理界面（AdminLTE）和 API 服务运行在不同的端口
2. API 请求路径统一为 /api/ 前缀
3. 客户端数据通过 WebSocket 或 AJAX 请求动态加载

问题根源分析

通过技术排查，发现问题的根本原因是 Nginx 反向代理配置未能正确处理 Pi-Hole v6 的新 API 路径。具体表现为：

1. /api/history/clients 等 API 接口返回 404 错误
2. 客户端相关页面（如 /admin/groups/clients）无法正常加载
3. 仪表盘无法获取客户端统计数据

解决方案

针对 Nginx 反向代理环境，需要以下配置调整：

1. 基础配置

location ^~ /admin/ {
    root /var/www/html;
    auth_basic "Restricted";
    auth_basic_user_file /var/www/html/pihole/.htpasswd;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://127.0.0.1:8001/admin/;
}

location ^~ /api/ {
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass http://127.0.0.1:8001/api/;
}

2. Pi-Hole FTL 配置

需要确保 Pi-Hole 的 FTL 服务监听正确的端口：

pihole-FTL --config webserver.port "127.0.0.1:8001"
service pihole-FTL restart
service nginx reload

技术原理

该解决方案的工作原理：

1. 将 /admin/ 路径的请求代理到 Pi-Hole 管理界面
2. 单独处理 /api/ 路径的请求，确保 API 调用正常
3. 通过设置正确的 WebSocket 端口，保证实时数据的传输
4. 保持认证信息（如 Basic Auth）的正确传递

最佳实践建议

1. 在升级 Pi-Hole 到 v6 版本时，应同步检查反向代理配置
2. 建议使用独立的端口配置，避免与其他服务冲突
3. 定期检查 Nginx 的访问日志，确保 API 请求正常
4. 对于复杂的网络环境，可考虑增加额外的 Header 配置

总结

Pi-Hole v6 的架构变化带来了更清晰的 API 分离，但也需要相应的代理配置调整。通过正确的 Nginx 配置和 FTL 服务端口设置，可以确保仪表盘各项功能正常显示，特别是客户端相关的统计信息。这一解决方案不仅适用于当前版本，也为未来可能的架构变化提供了配置参考模板。