基于 AdGuard Home 官方 API 的 DNS 过滤管理工具，支持黑白名单管理、状态监控与缓存清理，为家庭网络提供便捷的隐私保护控制。
说明：
## 核心用法
AdGuard Home Controller 是一款通过 HTTP API 管理 AdGuard Home DNS 过滤的命令行工具。用户需配置 `ADGUARD_URL`、`、`ADGUARD_USERNAME` 和 `ADGUARD_PASSWORD` 环境变量后，即可执行六大核心操作：：`check` 查询域名过滤状态、、`allow`/`/`block` 管理黑白名单、、`status` 查看 DNS 统计、、`toggle` 切换保护开关、、`cache-clear` 清除 DNS 缓存。所有操作均通过标准 REST API 与本地或局域网内的 AdGuard 实例通信，支持批量域名处理与配置文件持久化。
## 显著优点
1. **零侵入式管理**：无需登录 AdGuard Web 界面，命令行即可完成全部操作，适合自动化脚本集成
2. **安全设计规范**：密码通过环境变量传入，临时 cookie 文件带 PID 隔离并自动清理，无硬编码敏感信息
3. **功能覆盖完整**：涵盖日常管理所需的查询、放行、拦截、统计、开关、缓存清理全场景
4. **文档详尽实用**：提供从快速入门到故障排查的完整指南，包含规则语法说明与批量操作示例
5. **轻量无依赖**：仅依赖系统自带的 curl，无需额外安装运行时或库
## 潜在缺点与局限性
1. **网络环境受限**：仅支持 HTTP 协议（默认），若 AdGuard 未配置 HTTPS 则存在中间人攻击风险
2. **认证方式单一**：仅支持基础用户名/密码认证，缺乏双因素认证或 API Token 机制
3. **功能边界明确**：仅限于 DNS 过滤管理，无法配置上游 DNS、DHCP 设置等高级功能
4. **错误处理依赖 curl**：网络超时或 AdGuard 服务不可用时，错误信息直接暴露 curl 原始输出
5. **无并发控制**：批量操作时无速率限制，大量请求可能触发 AdGuard API 限流
## 适合的目标群体
– **家庭网络管理员**：需要快速放行误拦截网站或临时关闭过滤进行故障排查
– **DevOps/运维工程师**：将 DNS 管理集成到自动化运维工作流中
– **隐私安全爱好者**：通过命令行精细化控制网络层面的广告与追踪拦截
– **技术极客**：偏好 CLI 工具而非 Web GUI 的高效操作方式
## 使用风险
1. **凭证泄露风险**：密码以明文环境变量存储，若系统被入侵或历史记录未清理可能暴露
2. **误操作影响面广**：`toggle` 命令直接切换全网 DNS 保护状态，可能影响所有局域网设备
3. **缓存延迟问题**：规则变更后需手动执行 `cache-clear` 或等待客户端 TTL 过期，非即时生效
4. **网络可达性依赖**：AdGuard 实例离线或 IP 变更将导致所有命令失败，需提前规划高可用方案
会员专属
