跳转到内容
Router.Homes

AdGuard Home：从后台到终端过滤验证

完成后你能确认什么

Section titled “完成后你能确认什么”
  • AdGuard Home 接管 OpenWrt 的 53，Web 后台在 3000；
  • dnsmasq 退到 5353，仍负责 DHCP；
  • DHCP 客户端拿到 192.168.2.1 作为 DNS；
  • 自定义过滤规则生效，正常域名仍能解析；
  • 重启后数据盘、AGH 配置和过滤规则仍然存在。

适用环境与拓扑

Section titled “适用环境与拓扑”
  • PVE 9.2.2 单网口；OpenWrt 25.12.6 x86_64 VM 201（1GB RAM，2GB 数据盘）。
  • WAN net0 接 vmbr0（DHCP）；LAN net1 接独立 vmbr2（192.168.2.0/24）。
  • AGH 版本 0.107.79；apk 源里有 adguardhome 包。
  • 不要让两个 OpenWrt VM 的 DHCP 共享同一个 bridge：本实验 VM 200 在 vmbr1（192.168.1.0/24），VM 201 必须在 vmbr2（192.168.2.0/24），否则客户端可能拿到另一个网段的租约。
物理口PVE bridge虚拟网卡OpenWrt 接口职责
nic0vmbr0net0wan DHCP上游 192.168.50.1
—vmbr2net1lan 192.168.2.1AGH + DHCP 客户端

端口与职责

Section titled “端口与职责”
端口 组件 作用
53 AdGuard Home 客户端 DNS、过滤、上游转发
3000 AdGuard Home Web 管理后台
5353 dnsmasq DHCP 与本地 DNS（不再对客户端提供 53）

不要把 AGH 和 dnsmasq 同时绑在 53；也不要把 DHCP option 6 指向一个没有监听 53 的地址。

改动前准备

Section titled “改动前准备”
路由器 Shell备份配置并准备数据盘
终端窗口
cp /etc/config/dhcp /etc/config/dhcp.bak.$(date +%F)
cp /etc/config/adguardhome /etc/config/adguardhome.bak.$(date +%F) 2>/dev/null || true
cat /etc/config/dhcp

确认你能进 PVE 控制台或 OpenWrt LAN；不要把唯一管理入口建立在正在改的 DNS 上。

预期出问题时能恢复 dnsmasq/AGH 配置。

最小步骤

Section titled “最小步骤”
AdGuard Home 首次启动欢迎页，显示 Get Started 按钮和 Step 1/5
AGH 0.107.79 首次启动的欢迎页；点 Get Started 进入设置向导。截图来自临时实验环境，中文语言已切换。
路由器 Shell安装 AGH、数据盘工具和 fstab 支持
终端窗口
apk update
apk add adguardhome block-mount e2fsprogs

e2fsprogs 提供 mkfs.ext4；block-mount 提供 fstab 服务。国内网络慢时可换 OpenWrt 镜像源，但包必须通过签名校验。

预期adguardhome、block-mount、e2fsprogs 已安装。

路由器 Shell格式化并持久挂载数据盘

只对确认无数据的实验室数据盘操作：

终端窗口
mkfs.ext4 -F /dev/sdb
mkdir -p /opt/agh
mount /dev/sdb /opt/agh
block info /dev/sdb

用 block info 输出的 UUID，在 LuCI 的“挂载点”里把该磁盘目标设为 /opt/agh 并启用；或用 CLI 找到对应的 @mount[n]：

终端窗口
uci show fstab
# 找到 uuid 为 <你的-UUID> 的 @mount[n]
uci set fstab.@mount[n].target='/opt/agh'
uci set fstab.@mount[n].enabled='1'
uci commit fstab
/etc/init.d/fstab enable
block mount
mount | grep /opt/agh

本实验用的是已自动检测出的 fstab.@mount[2]（UUID 指向 2GB 数据盘），把 target 改为 /opt/agh、enabled 设为 1 后成功。不要照抄 [2]，按你的 UUID 找对应 section。

预期/opt/agh 挂在独立磁盘上，重启后仍在。

路由器 Shell把 dnsmasq 退到 5353
终端窗口
uci set dhcp.@dnsmasq[0].port='5353'
uci commit dhcp
/etc/init.d/dnsmasq restart
netstat -lnp | grep -E ':53|:5353'

此时客户端暂时无法用 53 解析；下一步启动 AGH。

预期53 端口空出来，DHCP 仍然正常。

路由器 Shell启动 AGH 首次配置
终端窗口
uci set adguardhome.config.work_dir='/opt/agh/work'
uci commit adguardhome
mkdir -p /opt/agh/work
chown -R adguardhome:adguardhome /opt/agh /etc/adguardhome
/etc/init.d/adguardhome enable
/etc/init.d/adguardhome start
sleep 3
netstat -lnp | grep -E ':3000|:53'

浏览器打开 http://192.168.2.1:3000/，设置：

  • Web 端口 3000；
  • DNS 端口 53；
  • 管理员账号/密码；
  • Upstream DNS 填 192.168.50.1（本实验环境）；
  • 如果上游不做 DNSSEC 验证，先关闭 DNSSEC，避免解析失败。

没有浏览器时可用 AGH 的 setup API；密码不要写进脚本或仓库。

预期Web 后台在 3000 可访问。

路由器 Shell让 DHCP 通告 AGH 地址
终端窗口
uci add_list dhcp.lan.dhcp_option='6,192.168.2.1'
uci commit dhcp
/etc/init.d/dnsmasq restart
uci show dhcp.lan | grep dhcp_option

只改 dnsmasq 端口而不加 option 6 时，部分客户端可能拿不到 DNS；本实验必须显式加。

预期客户端 DNS 是 192.168.2.1。

LuCI添加一个确定性过滤规则

在 AGH 后台 Filters → Custom filtering rules 添加：

||blocked.example^

这是测试用保留域名；真实使用再订阅维护中的过滤列表。不要用“拦截后网页打不开”来判断规则生效，先用 nslookup 看返回。

预期blocked.example 返回 0.0.0.0，正常域名不受影响。

验证

Section titled “验证”
AdGuard Home 中文仪表盘，显示 DNS 查询和过滤统计
完成安装后的仪表盘。刚配置完还没有查询时，统计为 0 是正常的；先确认 DNS 端口和上游可用。
路由器 Shell检查端口和本机解析
终端窗口
netstat -lnp | grep -E ':53|:3000|:5353'
nslookup blocked.example 192.168.2.1
nslookup openwrt.org 192.168.2.1

预期：blocked.example 返回 0.0.0.0（IPv6 可能同时显示 ::）；openwrt.org 返回真实地址。

预期AGH 监听 53/3000，dnsmasq 监听 5353。

电脑从 DHCP 客户端验证
终端窗口
ip addr show
ip route
cat /etc/resolv.conf
nslookup blocked.example
nslookup openwrt.org

如果客户端 DNS 不是 192.168.2.1，回到 DHCP option 6 和 dnsmasq 端口检查。

预期客户端拿到 192.168.2.x 和 DNS 192.168.2.1，拦截/正常解析都正确。

路由器 Shell重启后复验
终端窗口
reboot

重启后：

终端窗口
mount | grep /opt/agh
netstat -lnp | grep -E ':53|:3000'
nslookup blocked.example 192.168.2.1
nslookup openwrt.org 192.168.2.1

预期数据盘自动挂载，AGH 和过滤规则恢复。

失败分支与恢复

Section titled “失败分支与恢复”

AGH 起不来 / 53 被占用

Section titled “AGH 起不来 / 53 被占用”
终端窗口
logread | grep -i adguard | tail -50
netstat -lnp | grep ':53'
/usr/bin/AdGuardHome --check-config -c /etc/adguardhome/adguardhome.yaml

如果 dnsmasq 还在 53，先确认 dhcp.@dnsmasq[0].port='5353'；如果是配置错误，恢复备份：

终端窗口
cp /etc/adguardhome/adguardhome.bak.YYYY-MM-DD /etc/adguardhome/adguardhome.yaml
/etc/init.d/adguardhome restart

客户端完全无法解析

Section titled “客户端完全无法解析”

临时把 DNS 还给 dnsmasq：

终端窗口
uci set dhcp.@dnsmasq[0].port='53'
uci -q delete dhcp.lan.dhcp_option
uci commit dhcp
/etc/init.d/dnsmasq restart
/etc/init.d/adguardhome stop

先恢复基础解析，再逐项排查 AGH。

数据盘没挂上

Section titled “数据盘没挂上”
终端窗口
mount | grep /opt/agh
block info /dev/sdb
logread | grep -i fstab

检查 fstab 的 UUID、target、enabled；必要时手动 mount /dev/sdb /opt/agh 后重启 AGH。

过滤不生效

Section titled “过滤不生效”
AdGuard Home 过滤器页面，显示默认黑名单列表
过滤器页面可以看到已启用的黑名单。截图只显示默认列表，没有订阅第三方规则；自定义测试规则在设置向导/过滤规则里添加。
  • 确认 AGH 是客户端实际使用的 DNS；
  • 确认规则在 Custom filtering rules，不是订阅列表；
  • 用 nslookup blocked.example 192.168.2.1 直接问 AGH；
  • 浏览器/系统 DoH 可能绕过 AGH。

E2 实测记录（2026-10-20）

Section titled “E2 实测记录（2026-10-20）”
  • 环境：PVE 9.2.2 单网口；OpenWrt 25.12.6 VM 201（1GB/2GB 数据盘）；AGH 0.107.79。
  • 端口：AGH 53 + Web 3000；dnsmasq 5353；DHCP option 6 192.168.2.1。
  • 客户端：DHCP 192.168.2.166/24，DNS 192.168.2.1；blocked.example → 0.0.0.0，openwrt.org → 64.226.122.113。
  • 重启：/opt/agh 通过 fstab 自动挂载；AGH、dnsmasq、过滤规则恢复；Web 返回 302。
  • 未测：真实浏览器 UI 操作、外部订阅列表、物理 LAN 客户端、IPv6、长期稳定性。

来源与复核

Section titled “来源与复核”
  • 本页是 E2 实验记录；未做独立复核，也未在真实物理 LAN 上验证。
  • 复现配方：tests/recipes/agh-25.12-vm201.md；环境记录：docs/agh-e2-run.md。
  • AGH 版本/包名变化时更新 testedVersions；不要直接套用其他固件版本的 init 脚本。

来源

Router.Homes

独立的 OpenWrt 实操笔记。每页写明固件、设备、包管理器与恢复路径。

图标：Solar by 480 Design, CC BY 4.0