家里智能设备一多广告也跟着多起来。智能电视开机先放15秒广告手机App打开弹窗“福利”连个NAS下载都要忍受套娃推广。这些烦人东西其实有一个共同入口DNS。我折腾了一套方案用树莓派5跑OpenMediaVault 7也就是常说的OMV7在上面部署AdGuard Home直接从DNS解析层面把广告域名掐掉电视、手机、电脑全家设备一起清静。这套方案不只是去掉广告顺带把局域网域名解析速度也拉高了一截打开网页明显更跟手。适合有一点Linux基础、手里有树莓派或者打算搞家庭服务器的人参考。这套组合我用了大半年中间换过思路、踩过不少坑文章里会把完整过程和排查经验都写出来。技术原理不绕弯子直接给可落地的操作方法你照着做就能在自己家里把AdGuard Home跑起来。1. 方案选型为什么是树莓派5OMV7AdGuard Home1.1 树莓派5做家庭服务器性能够用且稳先解决最重要的问题用什么设备跑。树莓派5相比前代提升非常明显四核Cortex-A76主频最高能到2.4GHz配上8GB内存版本跑DNS解析服务完全是杀鸡用牛刀。AdGuard Home本身是Go语言写的CPU和内存占用极低实际跑起来内存占用也只有一两百MB树莓派5这块CPU应付几千个查询日志绰绰有余。更重要的一点是功耗。家里如果要7x24小时跑一个DNS过滤服务设备功耗不能太高。树莓派5整机功耗也就几瓦到十几瓦之间比一台旧电脑、软路由省电得多。而且树莓派5自带千兆网口在DNS这类小包转发场景下千兆和百兆差距不大但也不是说没差别至少后续你想在树莓派上挂别的服务千兆网口不会成为瓶颈。我建议买8GB版本多出来的内存不是给AdGuard Home用的是给你后续折腾其他服务留余地。毕竟树莓派5买回来一机多用是常态光跑一个DNS过滤有点浪费。供电一定要用官方USB-C电源树莓派5对电源质量比较敏感劣质电源会导致瞬间电压跌落重启DNS服务中断会让全家断网这就很伤。1.2 用OMV7做底座省掉裸机配置的碎活树莓派装完系统以后直接跑Docker和AdGuard Home其实也行命令敲完就完事。但问题是下次你还要装个Samba共享、挂个硬盘做轻NAS、给家里搞个相册备份如果每次都是裸机命令行配置前面配置的系统服务、挂载点、用户权限全部要重来一遍。OMV7OpenMediaVault 7这套基于Debian的开源NAS系统实际上就是给树莓派加了一个Web管理面板和一套成熟的存储管理体系。OMV7底层就是Debian树莓派生态完全兼容。它的插件系统里自带omv-extras装了之后可以很方便地启用Docker仓库然后在Web界面管理Docker容器和镜像。比如AdGuard Home的容器我可以直接在OMV7的Web UI里查看运行状态、看日志、重启不用每次SSH进去敲docker命令。我配置的硬盘共享、SMB服务也和家里的Windows、小米电视连接得非常好一个系统把存储和DNS全干了。选OMV7的另一个理由是不折腾系统。裸机用Debian的话你还需要自己配置防火墙、管理用户、处理软件源、设置开机自启。OMV7这些全都帮你做好了图形界面点两下就能完成大部分操作。我试过用树莓派5直接装Ubuntu Server来跑AdGuard Home确实轻量但后续给家人开共享文件夹、挂移动硬盘做备份时就发现还是得有个Web面板才方便。1.3 AdGuard Home比Pi-hole更契合国内家庭场景做DNS过滤很多人第一反应是Pi-hole。Pi-hole的老牌优势在生态但有两个问题在国内家庭环境里比较头疼一是国内魔改版的App和电视系统用了一些非标准解析链路需要细细调Pi-hole的规则生态更偏欧美网站二是Pi-hole的配置和界面相对复杂对非专业家庭用户不太友好。AdGuard Home的优势在于它本身就是商业广告屏蔽软件AdGuard的开源核心项目规则过滤的适配性做得很细支持DNS、IPv6、DNSCrypt面板中文支持也好看拦截日志、添加白名单都是在网页上点选学习成本低很多。而且AdGuard Home自带“DNS拦截清单”体系可以直接订阅社区维护的规则列表也支持自定义规则。就家用场景而言AdGuard Home的“查询日志”功能是真的能救命。谁家哪台设备在访问什么域名一目了然。排查某些刁钻App不能播放的问题时看日志就能定位到具体是哪个域名被拦了比单纯加黑名单灵性很多。2. 环境搭建树莓派5从烧录到跑起OMV72.1 硬件清单与系统烧录我实际用到的硬件和工具这里列一份完整清单避免你卡在某一步树莓派5推荐8GB版官方USB-C电源5V/5A别的电源容易掉电64GB以上TF卡或者建议直接用USB转SATA/SSD硬盘盒引出系统盘读卡器、另外准备一台电脑用于烧录系统一根网线直接连接树莓派到路由器TF卡在持续写入场景下寿命和速度都不太行如果是长期7x24小时跑服务我强烈建议你把系统直接装在USB固态硬盘上。树莓派5原生支持从USB启动把PI OS Lite系统镜像烧录到SSD里插上USB口通电就能启动容量和稳定性都好很多。烧录系统用的是树莓派官方的Raspberry Pi Imager也有跨平台版本。选择“Raspberry Pi OS Lite (64-bit)”这个不带桌面环境的版本跑服务用纯命令行的Lite版最合适桌面环境既占资源又没什么用处。烧录的时候注意Imager里在配置阶段就能预设账号密码、开启SSH服务直接填好省得后续再用显示器键盘去操作。烧录完成后把SSD插到树莓派上网线接路由器通电等待一两分钟就可以从电脑SSH登录了。2.2 安装OMV7的完整流程树莓派开机后第一件事就是更新系统保证后续软件源和内核一致sudo apt update sudo apt upgrade -y sudo reboot然后安装OMV7。官方脚本方式最省事但需要从GitHub拉取安装脚本网络畅通时执行一次就行。脚本会把Debian系统切成OMV7环境中间会有一些交互提示大部分时候按默认一路继续即可wget -O - https://github.com/OpenMediaVault-Plugin-Developers/installScript/raw/master/install | sudo bash这个脚本执行时间取决于树莓派5性能和网络速度我跑一次大约十几分钟。安装完之后Web管理面板地址就是树莓派当前的IP默认端口80比如http://192.168.1.100默认用户是admin默认密码是openmediavault登录后修改密码。这里插一句OMV7基于Debian 12系统里自带的软件源可能在国内速度一般。你如果访问官方源很慢可以自行换成国内镜像源但注意不要同时启用多个不同类型源容易包冲突。我用的是清华源速度稳定OMV的包也都能正常更新。2.3 在OMV7里准备好Docker运行环境OMV7本身不带Docker需要通过插件装。具体路径是“系统”-“插件”-“omv-extras”找到它并启用。启用之后在“系统”-“OMV-Extras”界面里勾选Docker仓库然后保存和安装。这样一来OMV的“服务”菜单里就会出现“Compose”和“Docker”两个子菜单后续镜像拉取、容器启停都可以在Web界面操作。如果你习惯命令行也可以直接在SSH里安装Docker用Docker官方脚本curl -fsSL https://get.docker.com | sudo bash sudo systemctl enable docker sudo systemctl start docker装好后顺手把当前用户加入docker组免得每条命令都要加sudosudo usermod -aG docker $USER这一步别省。不加的话每次docker compose都要sudo日志权限、目录挂载的权限问题会让你后期很煎熬。装完Docker后面部署AdGuard Home就顺畅了。3. AdGuard Home核心部署与配置3.1 用Docker Compose一次性拉起服务树莓派上跑AdGuard Home我推荐用Docker方式而不是直接apt安装。好处是后续升级、备份、迁移都方便不会在系统里洒一地把控件。而且OMV7里自带Compose管理整体流程非常顺。先在OMV7的文件系统里给AdGuard Home建两个持久化目录我用的是work放程序工作数据conf放配置文件。这一步很关键Docker容器是“一次性”的如果数据不挂载到宿主机容器重创后配置就全丢了mkdir -p /srv/omv/adguard/work mkdir -p /srv/omv/adguard/conf然后写docker-compose.yml。AdGuard Home官方建议使用host网络模式也就是让容器直接共享树莓派的网络好处是不用做端口映射DNS这种UDP服务在host模式下最稳容器重启时端口占用和NAT问题都会被绕开。Compose文件如下services: adguardhome: image: adguard/adguardhome:latest container_name: adguardhome restart: unless-stopped network_mode: host volumes: - /srv/omv/adguard/work:/opt/adguardhome/work - /srv/omv/adguard/conf:/opt/adguardhome/conf这个配置 traduzione 简单镜像用adguard/adguardhome:latest容器重启策略是unless-stopped只要不是手动停止服务器重启后容器也会自动跟着启动。host网络模式下AdGuard Home会直接监听树莓派的53、3000端口局域网其他设备访问树莓派IP就能用。在OMV7的Web界面“服务”-“Compose”里上传这段YAML点启动或者直接在SSH里docker compose up -d容器就起来了。第一次启动后访问http://树莓派IP:3000进入初始化页面。3.2 首次初始化管理密码与监听端口第一次访问Web管理页面时AdGuard Home会引导你配置。先设置管理界面端口默认3000但初始化完成后如果你想用80端口做管理可以直接在页面上改成80。这里要注意树莓派如果后面要装Nginx、web服务80端口容易冲突我在实际使用中把管理端口改到了8080保留80给其他服务端口冲突是后面排查麻烦最多的地方。接着设置DNS监听端口默认就是53保持默认。如果需要加密DNS可以选853或784但家庭内网用53就够内部网络不需要加密链路加密解析主要留给外网场景。然后设置管理员用户名和密码这一步自行设置即可。初始化完成后Web管理地址就变成你刚才设置的端口了。我用的是80端口以外的8080地址比如http://192.168.1.100:8080。注如果改了管理端口访问的时候URL里必须带端口号。3.3 设置上游DNS与去广告规则进入AdGuard Home管理页后第一件事就是配“设置”里的“DNS 设置”。上游DNS是AdGuard Home向外部DNS服务器发起域名解析请求时使用的服务器这是整个过滤效果的源头建议多填几个。我常用的上游DNS组合223.5.5.5和223.6.6.6阿里公共DNS119.29.29.29腾讯DNSPod180.76.76.76百度公共DNS2400:3200::1阿里IPv6家里面有IPv6的一定要填然后在“DNS 设置”下方找到“Bootstrap DNS 服务器”这个参数是为了解析上游DNS服务器自身域名用的如果你上游写的是IP地址Bootstrap就可以不填或填写其中一个IP。我用的是223.5.5.5。再往下是“速度限制”和“缓存”。AdGuard Home自带DNS缓存建议把缓存大小调到4MB或以上再开启乐观缓存。这样局域网内大量重复查询会在本地直接命中不反复发到上游实际体感是网页打开变快。去广告的关键是“过滤器”-“DNS 拦截清单”。点击“添加过滤器”从社区规则仓库复制规则列表的URL填入即可。我实测下来对于国内家庭场景下面这几个规则覆盖面和误杀率比较平衡AdGuard DNS 过滤器https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txtanti-AD国内App广告过滤https://anti-ad.net/easylist.txt乘风广告规则https://raw.githubusercontent.com/xinggsf/Adblock-Plus-Rule/master/rule.txt广告过滤器AdGuard Simplified Domain Names部分商业规则可根据实际效果取舍规则URL指向的网络来源都是各个社区维护的开源列表网络畅通时添加后点“检查更新”就能拉取。我不建议盲目订阅十几个列表规则太多会导致误杀率上升而且AdGuard Home每次刷新规则、匹配域名时都会多一些CPU开销。我自己稳定使用的规则就三个拦截率基本维持在15%到25%之间。3.4 自定义规则与白名单管理光靠内置规则和订阅列表还不够。家里总有一些App会用特殊域名规则列表拿它没辙。或者反过来规则列表把某个正常API域名给误杀了导致视频加载失败、App登录白屏。这时候自定义规则就派上用场。AdGuard Home规则语法和AdBlock基本一致。屏蔽格式是||example.com^表示拦截 example.com 及其所有子域名||example.com^则是白名单放行该域名。你在“过滤器”-“自定义过滤规则”里直接添加即可。我家里遇到过一个典型情况某电视App开机需要连接广告SDK的域名误杀后表现为“网络异常无法启动”但主视频流域名是另一个CDN地址并不受影响。查日志后定位到被拦截的域名加了白名单问题立刻解决。白名单优先级高于黑名单不用担心双重规则冲突。4. 全家设备流量接入与效果验证4.1 路由器DHCP统一指向树莓派AdGuard Home配置完成只是第一步真正让全家设备生效的是把局域网所有设备的DNS指向树莓派IP。最省事的做法是在路由器管理页面里把DHCP服务器下发的DNS服务器地址改成树莓派的IP这样所有通过DHCP获取IP的设备都会自动把解析请求发到AdGuard Home。具体路径因路由器而异大部分家用路由器在“网络”-“DHCP服务器”-“首选DNS服务器”里填写有些光猫拨号环境DNS是由光猫下发的这时候要改光猫侧设置或者把光猫改成桥接模式由后级路由器拨号并下发DNS。我有朋友没注意这一点在路由器上改了半天结果底下设备拿到的是光猫下发的DNS广告拦了个寂寞。改完之后重启一下家庭网络设备或者等待DHCP租约到期重新获取IP。验证方法是电脑上nslookup example.com看返回的DNS Server是不是树莓派IP。如果显示的还是路由器IP或运营商DNS说明没改成功继续排查。4.2 电视与手机的单独配置有些设备不听话比如智能电视有时候会内置固定的DNS不随DHCP走尤其是一些Android系统电视。这种情况下我建议在电视本身的网络设置里把IP设置从自动改为静态IP或手动配置DNSDNS1填树莓派IPDNS2留空或不填。不同电视操作路径有差异一般在“设置”-“网络”-“有线网络/无线网络”-“手动设置”里能找到。手机端平时不用单独配置只要路由器DHCP生效就行。如果你在外面想用AdGuard Home的过滤效果那需要另外做公网暴露或加密DNS这个不推荐新手折腾安全风险高。我自己只在家庭局域网内用它外面用手机流量时广告拦不拦无所谓。如果某台设备强制使用它自己的DNS你可以阶段性把这个设备断网重连一下看看日志里能不能看到它的查询。看不到说明它没走你的AdGuard Home需要手动指定。4.3 通过查询日志分析拦截效果AdGuard Home的“查询日志”是整个系统最有趣的部分。每台设备访问的每个域名都记录在案包括时间、客户端IP、查询域名、处理动作允许/过滤。你在“查询日志”里输入关键词搜索就能看到某个域名被哪条规则拦截了处理方式会显示“已过滤”。点进去可以看到匹配到的过滤规则方便决定是否加白名单。我在查询日志里体验过很多次“破案”过程。有一次家里的小米电视突然能看网络视频但打不开应用商城看了日志才发现商城的广告SDK域名被anti-AD规则拦了加白之后立刻恢复。还有一次手机银行App闪退查日志发现一行银行风控域名的子域名命中了某条广告规则害我删掉了一条并不需要的规则列表。拦截率怎么算在“仪表盘”里能看到今日查询总数、过滤百分比等指标。我家10多台设备日均查询量接近1万到2万条过滤比例大概在18%上下。这个数字取决于家里的设备数量和App使用习惯不用刻意追求高拦截率正常够用就好。4.4 IPv6环境下的DNS配置注意点如果你的宽带和路由器开了IPv6这里要特别留意。现在很多Android电视和手机会优先使用IPv6 DNS进行解析如果IPv6的DNS还是运营商默认值那广告拦截就不完整表现为一部分广告还能弹出来。AdGuard Home可以监听IPv6地址你需要在“DNS设置”里勾选IPv6监听并给树莓派分配一个可用的IPv6地址。路由器的DHCPv6下配置也和IPv4一样把DNS服务器指向树莓派的IPv6地址。如果家里没有IPv6环境那就不用管这一节。但以我自己的经验国内IPv6普及率相当高很多设备默认IPv6优先家里宽带即使没启用IPv6路由器后台也默认是开着的你最好进路由器后台看一眼IPv6开关关闭而无感的情况很常见。如果IPv6这块实在不想折腾也可以粗暴地在路由器里关闭IPv6功能让所有设备回到IPv4 DNS统一解析。不过这个方案会牺牲一些IPv6带来的性能提升我是建议把IPv6 DNS也配好一劳永逸。5. 常见问题与排查都是我自己踩过的坑5.1 端口53被systemd-resolved占用树莓派基于Debian系统里默认有个systemd-resolved服务它会占用本地53端口。当你启动AdGuard Home时容器报错“Permission denied”或者“listen tcp :53: bind: address already in use”多半就是这个原因。解决办法是编辑/etc/systemd/resolved.conf把DNSStubListener改为no[Resolve] DNSStubListenerno然后重启服务sudo systemctl restart systemd-resolved sudo systemctl restart adguardhome记得同时把系统自身的DNS指向文件/etc/resolv.conf里的内容处理好否则系统解析会受影响。可以给resolv.conf重新建立软链指向/run/systemd/resolve/resolv.conf或者手动改成公共DNS地址。我自己是把resolv.conf改成手动的确保树莓派自身解析正常。5.2 电视App播放异常该如何定位智能电视的App偶发性播放失败最大的可能就是某条广告规则把视频分发域名的某个子域名误杀了。处理流程我建议三步走第一步在AdGuard Home的查询日志里搜出报错时间点附近的域名看看是不是有“已过滤”动作第二步点进详情确认命中的规则是哪个过滤器导致的第三步把该域名加入自定义白名单。需要注意的坑是有些域名看着很像广告但其实是视频App的核心接口比如统计、账号、播放鉴权域名。直接加白可能让开屏广告复活但至少能正常播放。稍微权衡一下我一般把“播放相关”的白名单看得比广告拦截优先级高。识别方法就是看被过滤的域名在日志里出现的频率和访问时机集中在启动阶段的是广告集中在点击播放瞬间的是核心接口。5.3 Docker重启后配置无故丢失有段时间我的AdGuard Home容器每次系统重启后配置就重置后来发现是Compose文件里没写完整挂载路径配置保存在容器层容器重创就没了。AdGuard Home的配置目录是/opt/adguardhome/conf工作目录是/opt/adguardhome/work两个都要挂出来。另外一个习惯很重要在OMV7或系统层面定期备份conf目录。AdGuard Home的规则订阅列表、白名单、自定义规则都存这里丢了就要手动重配一遍非常痛苦。我是每个月把adguard整个目录打包存到NAS共享盘里恢复时只要把目录还原重新起容器就行。5.4 OMV7升级后AdGuard Home容器无法启动OMV7自己会更新内核和相关依赖有时候内核更新后Docker的网络栈会受影响容器表现为启动瞬间退出。排查办法是docker logs adguardhome看日志大多数提示是端口被占用或者镜像版本不对。AdGuard Homelatest标签更新很频繁有时候新版本改变启动逻辑而旧配置不兼容解决办法是进目录把conf/AdGuardHome.yaml备份然后启动一次全新容器让初始化重新生成配置再把自己的上游DNS和规则重新设置。为了避免这种麻烦我倾向于固定镜像版本比如adguard/adguardhome:v0.107.52这样除非手动更新否则不会因为自动拉取latest导致不可控变化。定期升级时我才会在周末手动改版本号更新前备份好配置实测下来稳定很多。5.5 规则误杀某个App不能登录规则误杀在去广告方案里简直是家常便饭。特别是anti-AD这类大而全的列表有时候会拦截到微信、支付宝等App的SDK统计域名现象表现为“网络请求失败”“加载中旋转”。我的排查习惯是先把出问题的App对应的域名从日志里搜出来区分是广告还是功能性域名。如果只是统计类域名被拦截一般App还能正常用但如果登录接口、支付确认、验证码接口被拦截那就麻烦大了。解决办法跟上面说法一样加白名单。另外一个更稳的做法是缩减订阅规则把一个总的“verified”列表留下其余容易误杀的列表去掉我最终留下的列表就只有AdGuard官方和anti-AD两个误杀率可控。6. 实测效果与后续扩展折腾完全套配置我专门观察了一周家里网络环境是光猫桥接 路由器拨号树莓派5网线直连路由器。把DHCP首选DNS改成树莓派IP之后所有设备的DNS查询都汇聚到AdGuard Home面板里打开电视、手机刷视频、电脑挂网盘整个网络感觉更干净了。智能电视开机广告基本消失App内的开屏广告少了一大半手机浏览网页时边缘的悬浮广告也没了偶尔残留一点是在App自家应用内渲染的图片广告这些不走DNS解析只能靠应用内屏蔽。再说网络速度。AdGuard Home本地缓存生效后局域网内重复访问的域名走本地解析体感上打开网页和App首屏的速度有一定提升。树莓派5的千兆网口和强悍CPU在这种场景下非常从容即便同时有几十台设备在线查询状态栏CPU占用也不到5%。内存占用基本稳定在200MB以内对8GB版本来说毫无压力。后续如果想继续把树莓派5榨出更多价值AdGuard Home只是其中一个服务。我在同一台树莓派5上还跑着Samba共享、Docker里的其他几个小服务。它完全有能力胜任开发板和边缘计算的角色比如部署轻量化的YOLOv5推理模型做目标检测实验或者在树莓派5上交叉编译Qt应用这些玩法跟AdGuard Home并不冲突一个设备可以同时承担多个角色。最后分享两个小技巧。一是AdGuard Home的“重写”→“DNS 重写”可以自定义域名解析比如把某台NAS设备绑定一个好记的名字nas.lan家里所有设备直接访问这个域名就行不用记IP。二是OmV7的Smart Monitoring或者系统计划任务里加一个定时任务定期执行docker compose pull和docker compose up -dAdGuard Home的规则和镜像就能保持自动更新省得手动维护。如果你的树莓派5已经落灰这个项目是让它重新上岗的好理由。