adguard

核心用法

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 变更将导致所有命令失败，需提前规划高可用方案