AdGuard Home 控制器

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

要求

• 运行并带有 Web 界面的 AdGuard Home
• 管理员用户名和密码
• curl已安装（通常在 macOS/Linux 上默认安装）

快速开始

# Set password once
export ADGUARD_PASSWORD=your_admin_password

# Use commands
./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"      # Your AdGuard IP and port
export ADGUARD_USERNAME="admin"                     # Usually 'admin' (default)
export ADGUARD_PASSWORD="your_admin_password"       # REQUIRED

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

配置文件替代方案

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

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

然后单独设置ADGUARD_PASSWORD以确保安全。

命令

检查<domain>

检查域名当前是否被阻止或允许。

./adguard.sh check doubleclick.net
# ✗ doubleclick.net IS BLOCKED
#   Blocked by: Adblock Plus filter

./adguard.sh check example.com
# ✓ example.com is NOT blocked (allowed)

allow<domain>| 白名单<domain>

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

./adguard.sh allow broken-site.com
# ✓ Added rule: @@||broken-site.com^
#   Domain: broken-site.com
#   Action: allow

block<domain>| 黑名单<domain>

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

./adguard.sh block spyware-domain.ru
# ✓ Added rule: ||spyware-domain.ru^
#   Domain: spyware-domain.ru
#   Action: block

status | stats

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

./adguard.sh status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# AdGuard Home Status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Protection: ✓ ENABLED
# 
# DNS Queries: 1,234
# Blocked by rules: 156
# Blocked by safe browsing: 23
# Safe search replacements: 5
# Block rate: 14%
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

toggle | protection

启用或禁用DNS保护。用于临时禁用过滤。

./adguard.sh toggle
# Disabling protection...
# ✓ Protection is now false

cache-clear

清除DNS缓存以立即应用规则更改。

./adguard.sh cache-clear
# Clearing DNS cache...
# ✓ Cache cleared

查找您的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 "Checking $domain..."
    adguard.sh check "$domain"
done

API参考

完整AdGuard Home API文档请参阅references/api.md for complete AdGuard Home API documentation.