介绍
# AdGuard Home Controller
通过 REST API 从命令行管理 AdGuard Home DNS 过滤。
## 要求
- 运行 AdGuard Home 且带有 Web 界面 - 管理员用户名和密码 - 已安装 `curl`（macOS/Linux 上通常默认安装）
## 快速开始
```bash # 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 实例设置环境变量：
```bash 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`（可选）：
```json { "url": "http://192.168.1.100:3000", "username": "admin" } ```
然后出于安全考虑单独设置 `ADGUARD_PASSWORD`。
## 命令
### check `<domain>`
检查当前域名是被阻止还是允许。
```bash ./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>` | whitelist `<domain>`
将域名添加到允许列表（白名单）。创建一个覆盖阻止列表的例外规则。
```bash ./adguard.sh allow broken-site.com # ✓ Added rule: @@||broken-site.com^ # Domain: broken-site.com # Action: allow ```
### block `<domain>` | blacklist `<domain>`
将域名添加到阻止列表。创建一个自定义阻止规则。
```bash ./adguard.sh block spyware-domain.ru # ✓ Added rule: ||spyware-domain.ru^ # Domain: spyware-domain.ru # Action: block ```
### status | stats
显示 DNS 过滤统计信息和保护状态。
```bash ./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 保护。对于暂时禁用过滤很有用。
```bash ./adguard.sh toggle # Disabling protection... # ✓ Protection is now false ```
### cache-clear
清除 DNS 缓存以立即应用规则更改。
```bash ./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 过滤规则语法：
| 规则 | 效果 | |------|--------| | `\|\|example.com^` | 阻止 example.com 及其子域名 | | `@@\|\|example.com^` | 允许 example.com（例外/白名单） | | `example.com` | 仅阻止确切的域名 | | `\|\|ad.example.com^` | 仅阻止 ad.example.com |
有关完整语法，请参阅 [API 参考](references/api.md)。
## 常见场景
### 允许一个被意外阻止的站点
```bash adguard.sh allow my-bank.com ```
### 阻止已知的恶意软件域名
```bash adguard.sh block malicious-tracker.xyz ```
### 检查域名是否正在被过滤
```bash adguard.sh check ads.google.com ```
### 查看今天的统计数据
```bash adguard.sh status ```
### 暂时禁用过滤（例如，用于故障排除）
```bash adguard.sh toggle ```
## 故障排除
**错误：身份验证失败** → 检查 `ADGUARD_PASSWORD` 是否正确且已设置 → 验证 `ADGUARD_URL` 指向正确的 IP 和端口
**错误：API 调用失败（HTTP 401）** → 身份验证失败，请检查凭据
**规则未生效** → 运行 `adguard.sh cache-clear` 清空 DNS 缓存 → 等待 5 分钟以上以让客户端刷新其缓存 → 重启设备的网络连接
**无法连接到 AdGuard** → 验证设备在同一网络上 → 检查防火墙未阻止端口 3000 -> Ping 设备：`ping <ip>`
## 高级：批量操作
阻止多个域名：
```bash for domain in tracker1.com tracker2.com tracker3.com; do adguard.sh block "$domain" done ```
检查多个域名：
```bash 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](references/api.md)。