核心用法
pihole-ctl 是一个专门用于管理本地 Pi-hole DNS 过滤服务器的技能。它通过直接查询 Pi-hole 的 FTL（Faster Than Light）SQLite 数据库获取精确统计，同时支持通过 CLI 执行管理服务操作。
主要功能模块：
1. 统计查询：使用 Python 脚本 query_db.py 直接读取 /etc/pihole/pihole-FTL.db，支持获取 24 小时拦截摘要、TOP 域名/客户端排行等。查询不经过 Pi-hole 的 Web API，延迟更低、数据更实时。
2. 服务控制：封装 pihole enable/disable 命令，快速切换广告拦截状态。
3. Blocklist 维护：提供 pihole -g（Gravity 更新）封装，用于刷新广告域名列表。
4. 审计分析：识别网络中"话多"的客户端和被拦截最多的域名，辅助网络调优。
显著优点
- 直接数据库访问：绕过 Web 界面，查询效率更高，适合自动化脚本集成
- 轻量无依赖：核心脚本仅使用 Python 内置
sqlite3，无需额外安装包 - 权限设计合理：区分只读查询（数据库访问）和管理操作（需 sudo），符合最小权限原则
- 本地优先：所有操作在本地完成，不依赖外部 API，隐私性更强
潜在缺点与局限性
- 本地单实例限制：仅支持管理运行该技能的同一台机器上的 Pi-hole，无法远程管理多台
- 权限配置门槛：需要手动将用户加入
pihole组或配置 sudo，对新手不够友好 - 数据库文件锁定风险：Pi-hole FTL 正在写入时，并发读取可能短暂阻塞
- 无 Web 界面替代：缺乏图形化管理能力，纯 CLI/JSON 输出
适合人群
- 自托管 Pi-hole 的家庭网络管理员
- 喜欢命令行和自动化运维的技术用户
- 需要定期生成拦截报告或集成到监控系统的开发者
常规风险
| 风险类型 | 说明 | 缓解建议 |
|---------|------|---------|
| 权限提升误用 | `pihole` CLI 需要 sudo，配置不当可能导致非特权用户获得过度权限 | 使用 `sudoers` 精确配置允许的命令，而非 blanket sudo |
| 数据库损坏 | 极端情况下频繁查询可能影响 FTL 写入性能 | 避免高频轮询，建议 5 分钟以上间隔 |
| 隐私泄露 | 查询结果包含真实网络流量模式，日志需妥善保管 | 确保 `pihole-FTL.db` 文件权限严格限制（640 或 600）|