pihole-ctl

核心用法

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. 开源可审计：代码完全公开，逻辑透明，便于管理员自行审查或定制修改。

潜在缺点与局限性

1. 本地部署限制：必须运行在 Pi-hole 所在服务器或具备数据库访问权限的节点上，无法远程管理多实例。
2. 功能边界清晰：仅支持查询与基础启停控制，缺乏高级功能如自定义黑名单管理、DHCP 配置、Group 策略调整等。
3. CLI 管理需特权：pihole enable/disable 等管理命令仍需 sudo 权限，自动化场景下需额外配置免密 sudo 或 systemd 权限委派。
4. 数据库路径硬编码：默认路径为 /etc/pihole/pihole-FTL.db，若 Pi-hole 使用非标准安装路径，需手动指定 --db 参数。
5. 无历史趋势分析：仅支持固定时间窗口（如最近 24 小时）的统计，缺乏长期数据聚合与可视化能力。

适合的目标群体

• 家庭网络管理员：已部署 Pi-hole 的个人用户，希望快速获取拦截统计而无需登录 Web 后台。
• Homelab 爱好者：拥有自托管基础设施的技术用户，需要将 Pi-hole 监控集成到自动化工作流或通知系统中。
• 小型办公网络运维：10-50 人规模的内网环境，需定期审计 DNS 查询行为或排查异常客户端。
• 隐私敏感用户：偏好本地数据处理、拒绝云端 API 依赖的去中心化倡导者。

使用风险

1. 权限配置风险：若错误地将用户加入过高权限组或授予数据库目录写权限，可能导致 FTL 数据库损坏。
2. 路径遍历隐患：虽然脚本本身对 --db 参数无过滤，但需确保调用方传入可信路径，避免恶意构造读取系统敏感文件（如 /etc/shadow）。
3. CLI 命令注入：若上层应用未对用户输入做过滤，直接将自然语言指令拼接为 pihole 命令参数，可能引发命令注入（尽管当前实现未暴露此接口）。
4. 性能影响：高频查询大型 FTL 数据库（如保留 365 天日志）可能短暂占用磁盘 I/O，影响 Pi-hole 实时解析性能。
5. 版本兼容性：Pi-hole FTL 数据库 schema 可能随版本升级变更，需关注 skill 与 Pi-hole 的版本匹配。