name: adguard
description: 通过 HTTP API 控制 AdGuard Home 的 DNS 过滤功能。适用于管理拦截列表/允许列表、检查域名过滤状态、开关防护或清除 DNS 缓存。支持拦截/放行域名、查看统计信息以及启用/禁用 DNS 过滤。

AdGuard Home 控制器

通过 REST API 从命令行管理 AdGuard Home 的 DNS 过滤。

前提条件

• 已运行并启用 Web 界面的 AdGuard Home
• 管理员用户名和密码
• 已安装 curl（macOS/Linux 系统通常已预装）

快速开始

# 一次性设置密码
export ADGUARD_PASSWORD=你的管理员密码

# 使用命令
./adguard.sh status
./adguard.sh check example.com
./adguard.sh allow broken-site.com
./adguard.sh block malware.ru

配置

为你的 AdGuard 实例设置环境变量：

export ADGUARD_URL="http://192.168.1.100:3000"      # 你的 AdGuard IP 地址和端口
export ADGUARD_USERNAME="admin"                     # 通常为 'admin'（默认值）
export ADGUARD_PASSWORD="你的管理员密码"             # 必需

将以上配置添加到 ~/.bashrc 或 ~/.zshrc 以实现持久化。

配置文件方式（可选）

创建 ~/.adguard/config.json（可选）：

{
  "url": "http://192.168.1.100:3000",
  "username": "admin"
}

出于安全考虑，单独设置 ADGUARD_PASSWORD 环境变量。

命令

check <域名>

检查域名当前是否被拦截或允许。

./adguard.sh check doubleclick.net
# ✗ doubleclick.net 已被拦截
#   拦截来源：Adblock Plus 过滤器

./adguard.sh check example.com
# ✓ example.com 未被拦截（已允许）

allow <域名> | whitelist <域名>

将域名添加到允许列表（白名单）。创建一条例外规则以覆盖拦截列表。

./adguard.sh allow broken-site.com
# ✓ 已添加规则：@@||broken-site.com^
#   域名：broken-site.com
#   操作：允许

block <域名> | blacklist <域名>

将域名添加到拦截列表。创建一条自定义拦截规则。

./adguard.sh block spyware-domain.ru
# ✓ 已添加规则：||spyware-domain.ru^
#   域名：spyware-domain.ru
#   操作：拦截

status | stats

显示 DNS 过滤统计信息和防护状态。

./adguard.sh status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# AdGuard Home 状态
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 防护状态：✓ 已启用
# 
# DNS 查询数：1,234
# 被规则拦截：156
# 被安全浏览拦截：23
# 安全搜索替换：5
# 拦截率：14%
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

toggle | protection

启用或禁用 DNS 防护。适用于临时关闭过滤功能。

./adguard.sh toggle
# 正在禁用防护...
# ✓ 防护状态已设为 false

cache-clear

清除 DNS 缓存，使规则更改立即生效。

./adguard.sh cache-clear
# 正在清除 DNS 缓存...
# ✓ 缓存已清除

查找你的 AdGuard Home 设备

如果你不知道 AdGuard 的 URL：

1. 路由器管理面板 — 查找名为 "AdGuard Home" 的设备或检查端口 3000
2. 局域网扫描 — 使用 nmap 或查看“已连接设备”
3. 如果运行在同一台机器上 — 默认为 http://localhost:3000
4. mDNS/Bonjour — 尝试 http://adguard-home.local:3000（取决于网络配置）

过滤规则语法

AdGuard 使用 DNS 过滤规则语法：

完整语法请参阅 API 参考。

常见使用场景

允许被误拦截的网站

adguard.sh allow my-bank.com

拦截已知的恶意软件域名

adguard.sh block malicious-tracker.xyz

检查域名是否被过滤

adguard.sh check ads.google.com

查看今日统计信息

adguard.sh status

临时禁用过滤（例如用于故障排除）

adguard.sh toggle

故障排除

错误：身份验证失败
→ 检查 ADGUARD_PASSWORD 是否正确设置
→ 确认 ADGUARD_URL 指向正确的 IP 和端口

错误：API 调用失败 (HTTP 401)
→ 身份验证失败，请检查凭据

规则未生效
→ 运行 adguard.sh cache-clear 以刷新 DNS 缓存
→ 等待 5 分钟以上，让客户端刷新其缓存
→ 重启设备的网络连接

无法连接到 AdGuard
→ 确认设备在同一网络中
→ 检查防火墙是否阻止了端口 3000
→ 尝试 ping 设备：ping <IP地址>

高级操作：批量处理

拦截多个域名：

for domain in tracker1.com tracker2.com tracker3.com; do
    adguard.sh block "$domain"
done

检查多个域名：

for domain in example.com test.org my-site.net; do
    echo "正在检查 $domain..."
    adguard.sh check "$domain"
done

API 参考

完整的 AdGuard Home API 文档请参阅 references/api.md。