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

核心功能

AdGuard 是一款面向本地网络 DNS 过滤管理的命令行工具，通过调用 AdGuard Home 的 REST API，让用户无需打开 Web 界面即可完成日常运维操作。核心功能包括：

• 域名状态检查：实时查询指定域名是否被拦截及拦截来源
• 黑白名单管理：快速添加允许规则（@@||domain^）或拦截规则（||domain^）
• 全局控制：一键启用/禁用 DNS 保护，清除缓存使规则即时生效
• 统计概览：查看查询量、拦截率、安全浏览触发次数等关键指标

显著优点

极简部署：纯 Shell 脚本实现，零第三方依赖，仅需系统自带的 curl、grep、sed
安全意识到位：密码通过 ADGUARD_PASSWORD 环境变量传入，无明文硬编码；支持 ~/.adguard/config.json 分离配置与凭证
操作直观：命令语义清晰（check/allow/block/status/toggle），输出带 ✓/✗ 状态标识，适合自动化脚本集成
本地闭环：所有 API 调用限定于用户配置的内网地址（默认 192.168.x.x:3000 或 localhost），无数据外泄风险

局限与注意事项

• 依赖 AdGuard Home 实例：本身不提供过滤能力，需用户已部署 AdGuard Home 服务
• 网络可达性要求：运行设备须与 AdGuard 实例处于同一网络或路由可达
• HTTP 明文传输：默认使用 HTTP，若 AdGuard 未配置 HTTPS，凭证在局域网内明文传输（建议生产环境启用 HTTPS）
• 无域名格式校验：当前未对输入域名做严格合法性验证，无效输入可能产生无意义的规则

适合人群

• 家庭网络管理员：快速解误拦、添加自定义规则
• 运维自动化场景：批量域名管理、定时统计采集
• 隐私敏感用户：偏好命令行、不愿频繁登录 Web 后台

常规风险

• 凭证泄露风险：若将密码写入 .bashrc 未限制文件权限（建议 chmod 600），或多用户系统下环境变量暴露
• 误操作风险：toggle 直接切换保护状态，无二次确认，脚本调用时需谨慎
• 缓存延迟：规则变更后客户端 DNS 缓存可能需 5 分钟以上刷新，非工具本身可控