Adguard

核心用法

AdGuard Home Controller 是一款命令行工具，通过 AdGuard Home 的 REST API 实现对 DNS 过滤服务的远程管理。用户需配置环境变量（URL、用户名、密码）后即可执行多种操作：

• 状态监控：查看 DNS 查询量、拦截率、保护开关状态
• 域名检查：验证指定域名是否被拦截及拦截来源
• 黑白名单管理：快速添加允许或拦截规则，支持标准 AdGuard 过滤语法
• 保护切换：临时启用/禁用 DNS 过滤，便于故障排查
• 缓存清理：强制刷新 DNS 缓存使规则立即生效

显著优点

1. 零图形界面依赖：纯 CLI 设计，适合 SSH 远程管理、自动化脚本集成
2. 操作原子化：单一命令完成特定任务，学习成本低
3. 规则语法完整：支持 ||domain^ 标准语法，可精确控制子域名匹配
4. 配置灵活：支持环境变量与 JSON 配置文件双模式，密码可分离存储提升安全

潜在缺点与局限性

• 网络依赖：必须能直接访问 AdGuard Home 的 3000 端口，跨网段或公网部署需额外配置
• 无批量原生支持：多域名操作需自行编写 shell 循环
• 权限单一：依赖 AdGuard 管理员账户，无角色分级机制
• 无审计日志：操作记录依赖 AdGuard 服务端，工具本身不保留执行历史

适合人群

• 家庭网络管理员：快速修复误拦截网站
• 运维工程师：批量初始化 DNS 策略或集成 CI/CD 流水线
• 安全研究者：临时封堵恶意域名进行应急响应

常规风险

• 凭据泄露：ADGUARD_PASSWORD 明文存储于环境变量，共享终端或 history 日志可能暴露
• 误操作影响面大：block/allow 立即生效，若配置错误可能导致全家网络中断
• API 无二次确认：toggle、cache-clear 等操作无交互确认，脚本中需谨慎使用
• 版本兼容性：依赖 AdGuard Home 的 REST API，重大版本更新可能导致接口变更

核心用法

AdGuard Home Controller 是一款面向家庭网络用户的命令行工具，通过 HTTP API 与 AdGuard Home 实例交互，实现 DNS 过滤的精细化管理。用户需先配置 ADGUARD_URL、ADGUARD_USERNAME 和 ADGUARD_PASSWORD 环境变量，随后可通过 ./adguard.sh 执行各类操作。

主要功能模块：

| 命令 | 用途 |

|------|------|

| `check <domain>` | 查询域名过滤状态 |

| `allow/blacklist <domain>` | 添加白名单/黑名单规则 |

| `status/stats` | 查看 DNS 查询统计与防护状态 |

| `toggle` | 快速启停 DNS 过滤保护 |

| `cache-clear` | 清除 DNS 缓存使规则生效 |

典型工作流： 当用户发现某合法网站被误拦时，执行 ./adguard.sh allow broken-site.com 添加例外规则；若需阻止新发现的恶意域名，则使用 ./adguard.sh block malware.ru。规则变更后建议运行 cache-clear 确保即时生效。

显著优点

1. 零依赖设计：仅依赖系统预装的 curl、grep、sed，无需额外安装包管理器或运行时环境
2. 安全凭证管理：密码通过环境变量注入，配置文件可独立存储非敏感信息，符合安全最佳实践
3. 轻量高效：Shell 脚本实现，启动即时，资源占用极低，适合路由器等嵌入式环境
4. 操作原子化：每个命令对应单一 API 调用，失败状态明确，便于脚本集成和自动化

潜在局限

• HTTPS 非强制：默认示例使用 HTTP，虽限于内网通信，但缺乏传输层加密引导
• 输入验证薄弱：域名参数未做严格格式校验，依赖 AdGuard API 后端容错
• 个人维护来源：仓库创建于 2026-01，星标数为 0，长期维护可持续性待观察
• 功能边界清晰：仅覆盖核心过滤管理，不支持 AdGuard Home 的 DHCP 设置、客户端配置等高级功能

适合人群

• 家庭网络管理员，需快速调整 DNS 过滤规则
• 隐私意识用户，希望本地化命令行工具替代 Web 界面操作
• 自动化运维场景，需将 DNS 管理集成到现有脚本工作流

常规风险

低风险项：HTTP 明文通信限于内网，实际暴露面可控；个人开发者来源但代码透明，恶意注入可能性低。

缓解建议：生产环境配置 HTTPS 端点；对输入域名添加客户端正则校验；持续关注仓库更新动态。