AdBlock DNS

在 DNS 层面实现全网范围的广告与追踪器拦截。这是一个以 OpenClaw 技能形式直接运行于本机的 Pi-hole 替代方案，无需额外硬件。

功能说明

该技能在本机运行一个 DNS 陷井（sinkhole）服务器，可拦截整个网络中广告、追踪器、恶意软件及遥测（telemetry）相关的域名请求。任何将本机设为 DNS 服务器的设备（包括手机、平板、智能电视、笔记本电脑、IoT 设备等）均可自动获得无广告浏览体验。

使用与 Pi-hole 相同的主流屏蔽列表（Steven Black、AdAway、EasyList、EasyPrivacy、Anti-Malware），可拦截超过 18.9 万个广告与追踪器域名；同时支持 IPv4（A 记录）和 IPv6（AAAA 记录）查询的拦截。

可有效拦截： 网站横幅广告、追踪像素（tracking pixels）、第三方广告网络（如 Doubleclick、Amazon Ads、Criteo、Rubicon 等）、App 内广告、遥测/分析追踪器、恶意软件相关域名。

无法拦截： YouTube 广告、Twitch 广告，或任何与内容本身同源（same domain）提供的广告。这些平台通常通过自有 CDN（例如 YouTube 使用 googlevideo.com）分发广告，若直接屏蔽该域名将导致整个服务不可用。这是所有 DNS 级别拦截工具（包括 Pi-hole）的根本性限制。如需屏蔽 YouTube 广告，请使用 uBlock Origin 等浏览器扩展。

工作原理

该技能在本机运行一个 DNS 服务器。当设备发起域名查询时：

• 若该域名为屏蔽列表中所含条目，则返回 0.0.0.0（表示已拦截）
• 若该域名未被屏蔽，则将查询转发至上游 DNS（默认为 Cloudflare 的 1.1.1.1）

所有 DNS 查询均被记录并统计（包括总查询数、拦截率、被拦截最多的域名等）。

安装配置

步骤 1：运行安装脚本

cd /path/to/skills/adblock/scripts
bash setup.sh

该脚本将执行以下操作：

1. 按需安装依赖项
2. 创建 systemd 服务（以 root 权限运行，开机自启，崩溃后自动重启）
3. 下载屏蔽列表（涵盖约 15 万以上域名）
4. 在端口 53 启动 DNS 服务器
5. 在端口 8053 启动统计信息 API 服务
6. 输出本机 DNS IP 地址及设备配置指引

用户在安装过程中需输入一次 sudo 密码。

替代方式（不使用 systemd，手动启动）：

sudo node dns-server.js

步骤 2：修改设备的 DNS 设置

此为关键步骤。 DNS 服务器仅在设备主动指向它时才生效。

获取本机本地 IP 地址：

hostname -I | awk '{print $1}'

随后，将各设备的 DNS 服务器设置为该 IP 地址：

路由器（全网统一拦截）：

• 登录路由器管理后台（通常地址为 192.168.1.1）
• 找到 DNS 设置项（通常位于 DHCP 或 Internet/WAN 设置中）
• 将主 DNS 设置为本机 IP 地址
• 将备用 DNS 设置为 1.1.1.1（当本机离线时作为回退）
• 此时局域网内所有设备均已受保护

单个设备配置：

• iPhone/iPad： 设置 → Wi-Fi → 点击当前连接的网络 → 配置 DNS → 手动 → 添加本机 IP 地址
• Android： 设置 → 网络 → Wi-Fi → 当前网络 → 高级 → DNS → 设置为本机 IP 地址
• Mac： 系统设置 → 网络 → Wi-Fi → 详细信息 → DNS → 添加本机 IP 地址
• Windows： 设置 → 网络 → Wi-Fi → 硬件属性 → DNS 服务器分配 → 手动 → 设置 IPv4 DNS
• Linux： 编辑 /etc/resolv.conf，或使用 NetworkManager：nmcli con mod "Wi-Fi" ipv4.dns "MACHINE_IP"

步骤 3：验证是否生效

# 应返回 0.0.0.0（表示已被拦截）
nslookup ads.google.com MACHINE_IP

# 应返回真实 IP 地址（表示放行）
nslookup google.com MACHINE_IP

或通过 API 检查：curl http://localhost:8053/stats

Agent 命令

当用户询问广告拦截相关操作时，请使用以下命令：

查看统计信息

curl -s http://localhost:8053/stats | python3 -m json.tool

返回内容包括：总查询数、被拦截查询数、拦截率、被拦截最多的域名。

将域名加入白名单

若某网站因误拦截而无法正常访问：

curl -s -X POST http://localhost:8053/whitelist/add -H "Content-Type: application/json" -d '{"domain":"example.com"}'

将域名加入黑名单

curl -s -X POST http://localhost:8053/blacklist/add -H "Content-Type: application/json" -d '{"domain":"annoying-site.com"}'

检查域名是否被拦截

curl -s "http://localhost:8053/check?domain=ads.google.com"

更新屏蔽列表

屏蔽列表默认每 24 小时自动更新。如需立即强制更新：

curl -s -X POST http://localhost:8053/update

查看白名单

curl -s http://localhost:8053/whitelist

作为系统服务运行

setup.sh 脚本已自动完成服务配置。如需手动管理服务，请使用以下命令：

sudo systemctl start adblock-dns     # 启动服务
sudo systemctl stop adblock-dns      # 停止服务
sudo systemctl restart adblock-dns   # 重启服务
sudo systemctl status adblock-dns    # 查看服务状态
journalctl -u adblock-dns -f         # 实时查看日志

# 彻底卸载服务
sudo systemctl disable adblock-dns
sudo rm /etc/systemd/system/adblock-dns.service
sudo systemctl daemon-reload

配置文件

编辑 data/config.json 文件：

{
  "upstream": "1.1.1.1",   // 上游 DNS（可选 Cloudflare、Google 8.8.8.8 等）
  "port": 53,              // DNS 服务端口（53 为标准端口，需 root 权限）
  "apiPort": 8053           // 统计 API 端口
}

相关文件

• data/blocklist.txt —— 合并生成的屏蔽列表（自动生成）
• data/whitelist.txt —— 白名单域名（每行一个）
• data/custom-blacklist.txt —— 自定义额外屏蔽域名（每行一个）
• data/stats.json —— 查询统计信息
• data/config.json —— 服务配置文件

使用约束

• 端口 53 需要 root / sudo 权限
• 设备必须显式配置为使用本机 IP 作为 DNS 服务器，拦截功能方可生效
• 若本机离线，所有将其设为 DNS 的设备将失去域名解析能力（请务必配置备用 DNS 作为回退）
• 仅拦截域名层级请求，无法移除网页内的广告元素（此类需求请使用浏览器广告拦截扩展）
• 绕过系统 DNS 的 HTTPS/DoH 查询（如部分 App 或浏览器启用 DoH 后）将不会被拦截