本地 Pi-hole 智能监控管家

开源社区维护的 Pi-hole 管理工具，通过只读 SQL 查询本地 FTL 数据库，为家庭网络管理员提供安全的广告拦截统计与监控能力。

基本信息

• 技能名称?pihole-ctl
• 中文名称?本地 Pi-hole 智能监控管家
• 作者?1999AZZAR
• 分类?其他
• 版本?未标注
• 标签?devops, networking, privacy, automation, data-analytics, backend

使用方法

使用说明
核心用法
pihole-ctl 是一款面向本地 Pi-hole 实例的管理与监控技能，主要服务于家庭网络环境中的 DNS 广告拦截场景。其核心功能分为两大模块：一是 统计查询 ，通过 Python 脚本直接读取 Pi-hole 的 FTL 数据库（SQLite），获取 24 小时内的广告拦截量、Top 查询域名、最活跃客户端等关键指标；二是 服务管理 ，支持通过标准 CLI 命令启用/禁用拦截功能、更新 Gravity 黑名单数据库。用户可通过自然语言触发，如询问"今天拦截了多少广告"或"Pi-hole 状态如何"，系统即返回结构化的 JSON 数据或命令执行结果。
显著优点

1. 数据准确性高 ：直接查询 FTL 数据库而非依赖 Web 界面 API，避免缓存延迟，统计结果实时可靠。
2. 安全设计严谨 ：数据库连接采用 mode=ro 只读 URI 模式，从根本上杜绝误写风险；SQL 查询全面使用参数化语句，彻底消除注入攻击面。
3. 零外部依赖 ：仅依赖 Python 标准库（sqlite3、json、argparse 等），无需安装第三方包，部署简洁且供应链攻击风险极低。
4. 权限最小化 ：仅需读取数据库文件的权限，无需 root 特权即可运行核心查询功能，符合安全运维最佳实践。
5. 开源可审计 ：代码完全公开，逻辑透明，便于管理员自行审查或定制修改。
   潜在缺点与局限性
6. 本地部署限制 ：必须运行在 Pi-hole 所在服务器或具备数据库访问权限的节点上，无法远程管理多实例。
7. 功能边界清晰 ：仅支持查询与基础启停控制，缺乏高级功能如自定义黑名单管理、DHCP 配置、Group 策略调整等。
8. CLI 管理需特权 ： pihole enable/disable 等管理命令仍需 sudo 权限，自动化场景下需额外配置免密 sudo 或 systemd 权限委派。
9. 数据库路径硬编码 ：默认路径为 /etc/pihole/pihole-FTL.db ，若 Pi-hole 使用非标准安装路径，需手动指定 --db 参数。
10. 无历史趋势分析 ：仅支持固定时间窗口（如最近 24 小时）的统计，缺乏长期数据聚合与可视化能力。
    适合的目标群体
    家庭网络管理员 ：已部署 Pi-hole 的个人用户，希望快速获取拦截统计而无需登录 Web 后台。
    Homelab 爱好者 ：拥有自托管基础设施的技术用户，需要将 Pi-hole 监控集成到自动化工作流或通知系统中。
    小型办公网络运维 ：10-50 人规模的内网环境，需定期审计 DNS 查询行为或排查异常客户端。
    隐私敏感用户 ：偏好本地数据处理、拒绝云端 API 依赖的去中心化倡导者。
    使用风险
11. 权限配置风险 ：若错误地将用户加入过高权限组或授予数据库目录写权限，可能导致 FTL 数据库损坏。
12. 路径遍历隐患 ：虽然脚本本身对 --db 参数无过滤，但需确保调用方传入可信路径，避免恶意构造读取系统敏感文件（如 /etc/shadow ）。
13. CLI 命令注入 ：若上层应用未对用户输入做过滤，直接将自然语言指令拼接为 pihole 命令参数，可能引发命令注入（尽管当前实现未暴露此接口）。
14. 性能影响 ：高频查询大型 FTL 数据库（如保留 365 天日志）可能短暂占用磁盘 I/O，影响 Pi-hole 实时解析性能。
15. 版本兼容性 ：Pi-hole FTL 数据库 schema 可能随版本升级变更，需关注 skill 与 Pi-hole 的版本匹配。