AdGuard Home 自建 DNS 去广告教程：Docker 部署、全屋接管与排错

家里设备越来越多，浏览器插件只能管住一台电脑，手机、电视、平板和 IoT 设备依旧会看到广告。AdGuard Home 的思路不一样：它把广告拦截放到 DNS 层，只要设备使用它做 DNS，整个局域网都能统一过滤。下面从一台常开的 Linux 小主机开始，完成 Docker 部署、初始化、上游 DNS、过滤规则、路由器下发和常见故障排查。

先说明边界：AdGuard Home 是 DNS 过滤器，不是万能去广告器。它能拦截广告域名、跟踪域名和部分恶意域名，但无法去掉视频内嵌广告、与正文同域名的广告，也无法替代浏览器扩展的页面元素隐藏功能。

一、部署前先想清楚三件事#

第一，AdGuard Home 需要一台长期开机、局域网 IP 固定的设备。软路由、NAS、树莓派、迷你主机都可以；不建议直接装在正在承担拨号、DHCP、DNS 的主路由上，除非你很清楚端口冲突和故障回滚。

第二，确认局域网里没有别的程序占用 53 端口。AdGuard Home 的 DNS 服务默认监听 53/TCP 和 53/UDP，Web 管理页面默认监听 3000/TCP。很多 Linux 发行版自带的 systemd-resolved、dnsmasq 或 Pi-hole 都会占用 53。

第三，提前规划地址。下面用 192.168.1.10 作为 AdGuard Home 的局域网地址，用 192.168.1.1 作为路由器地址。实际部署时替换成自己的网段，不要照抄。

二、用 Docker 部署 AdGuard Home#

先安装 Docker。以 Debian/Ubuntu 为例，使用官方安装脚本最省事；生产环境也可以按发行版文档安装：

curl -fsSL https://get.docker.com | sh
sudo systemctl enable --now docker
docker --version

创建两个持久化目录。配置和数据分开放，后续备份、迁移会清楚很多：

sudo mkdir -p /opt/adguardhome/work
sudo mkdir -p /opt/adguardhome/conf

拉取镜像并启动。下面只映射局域网真正需要的 53 和 3000 端口，不把管理页面和 DNS 直接暴露到公网：

docker pull adguard/adguardhome

docker run -d \
  --name adguardhome \
  --restart unless-stopped \
  -p 53:53/tcp \
  -p 53:53/udp \
  -p 3000:3000/tcp \
  -v /opt/adguardhome/work:/opt/adguardhome/work \
  -v /opt/adguardhome/conf:/opt/adguardhome/conf \
  adguard/adguardhome

检查容器状态和日志：

docker ps --filter name=adguardhome
docker logs -f adguardhome

如果更喜欢 Compose，可以保存为 docker-compose.yml：

services:
  adguardhome:
    image: adguard/adguardhome
    container_name: adguardhome
    restart: unless-stopped
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "3000:3000/tcp"
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf

然后执行 docker compose up -d。Bridge 网络下，AdGuard Home 查询日志里看到的客户端地址可能是 Docker 网关地址（例如 172.17.0.1），而不是手机或电脑的真实 IP。如果你需要按客户端统计、按客户端设置规则，Linux 主机可以使用 --network host；代价是容器不再做端口映射，端口直接占用宿主机网络。Docker Desktop for Mac/Windows 不支持 host 网络模式。

三、完成初始化向导#

浏览器打开：

http://192.168.1.10:3000

进入初始化页面后，按下面思路设置：

1. 管理界面监听 0.0.0.0:3000，这样局域网内可以访问；如果只打算通过反向代理访问，也可以在初始化完成后改成只监听本机地址。
2. DNS 服务监听 0.0.0.0:53。如果 53 被占用，先不要继续，回到上一节处理端口冲突。
3. 设置管理员用户名和强密码。不要使用 admin/admin 这类默认组合。
4. 完成后进入仪表盘，先不要急着改路由器，先在电脑上单独测试解析。

如果 3000 端口打不开，依次检查：容器是否在运行、宿主机防火墙是否放行、云主机安全组是否放行、端口是否被其他程序占用。不要为了省事把 3000 直接暴露到公网。

四、处理 53 端口冲突#

先看谁占用了 53：

sudo ss -lunpt | grep ':53 '
sudo lsof -i :53

最常见的是 systemd-resolved。它默认在 127.0.0.53:53 上提供本地解析服务，会与 AdGuard Home 冲突。可以关闭它的 DNS stub listener：

sudo mkdir -p /etc/systemd/resolved.conf.d

sudo tee /etc/systemd/resolved.conf.d/adguardhome.conf > /dev/null <<'EOF'
[Resolve]
DNS=127.0.0.1
DNSStubListener=no
EOF

sudo mv /etc/resolv.conf /etc/resolv.conf.backup
sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
sudo systemctl reload-or-restart systemd-resolved

执行后重新检查 53 端口，再重启 AdGuard Home 容器。若占用者是 dnsmasq、Pi-hole 或路由器上的 DNS 服务，应二选一：停掉旧服务，或让 AdGuard Home 改听另一个 IP/端口。DNS 客户端通常只认 53，所以“改端口”只适合做上游或测试，不适合作为局域网 DNS 入口。

如果 AdGuard Home 和路由器在同一台设备上，先确认路由器的 WAN DNS 不要指向 AdGuard Home，否则容易形成 DNS 回环。正确关系是：局域网客户端 → AdGuard Home → 公网上游 DNS。

五、配置上游 DNS 和 Bootstrap DNS#

打开「设置 → DNS 设置」。上游 DNS 负责把 AdGuard Home 没命中过滤规则的域名继续解析。国内网络环境建议优先选择低延迟的国内解析器，再按需要加一个加密上游：

建议上游保留 2 到 3 个，不要堆十几个。Bootstrap DNS 填能直接解析 DoH/DoT 域名的 IP，例如 223.5.5.5 和 119.29.29.29。如果上游选择了加密 DNS，但 Bootstrap 写错，表现通常不是“报错”，而是解析超时或部分域名失败。

保存后在本机测试。假设 AdGuard Home 地址是 192.168.1.10：

nslookup example.com 192.168.1.10
dig @192.168.1.10 example.com +short
dig @192.168.1.10 doubleclick.net +short

第一条应正常返回 IP；被过滤规则命中的域名通常返回 0.0.0.0 或 ::。如果本机测试都不通，不要继续改路由器，先看 AdGuard Home 日志和上游设置。

六、添加过滤规则#

AdGuard Home 自带 AdGuard DNS filter，一般已经够用。打开「过滤器 → DNS 封锁清单 → 添加」，再按需增加规则。规则不是越多越好，重复规则会增加内存和解析开销，也可能误伤正常服务。

更新间隔建议 1 到 3 天。添加后观察「查询日志」和「统计」：如果某个正常网站被拦截，在日志里找到域名，加入「允许清单」；不要因为一次误杀就删掉整条规则。过滤规则主要拦截域名级请求，页面内广告位、视频贴片、同域广告仍可能需要浏览器扩展配合。

七、让全屋设备真正走 AdGuard Home#

推荐顺序是先在电脑或手机上手动把 DNS 改成 192.168.1.10，确认能上网、能过滤，再去改路由器。这样出问题时可以快速恢复。

路由器上找到 DHCP 设置里的「DNS 服务器」或「主 DNS / 备用 DNS」，填写 AdGuard Home 的局域网地址。只填一个地址通常比同时填两个更可靠：如果备用 DNS 填了运营商 DNS 或 8.8.8.8，部分设备会绕过 AdGuard Home。

客户端 → 路由器 DHCP 下发 DNS 192.168.1.10 → AdGuard Home:53 → 公共上游 DNS

同时检查路由器的 IPv6 DNS 设置。很多设备会优先使用 IPv6 DNS，如果只改了 IPv4，手机和电视可能仍然走运营商解析。处理方式有两种：把 IPv6 DNS 也指向 AdGuard Home 的 IPv6 地址，或者在路由器上关闭 IPv6 DNS 下发，只保留 IPv4 DNS。

如果路由器不允许自定义 DHCP DNS，可以让 AdGuard Home 接管 DHCP（需要 67/UDP，容器建议使用 host 网络），或者逐台设备手动设置。不要在路由器上把 LAN DNS 指向 AdGuard Home 的同时，又把 AdGuard Home 的上游设置为路由器自身，这会形成循环。

验证时不要只看网页能不能打开，应该看 AdGuard Home 仪表盘是否出现对应客户端和查询记录：

nslookup example.com
nslookup doubleclick.net

电脑、手机、电视分别测一次。若某个设备没有出现在「客户端」里，通常是它仍在使用缓存、走了 IPv6 DNS、开了私人 DNS，或者连接的是访客网络。

八、可选：给管理页面加 HTTPS#

局域网内用 HTTP 访问 3000 端口通常可以接受；如果希望密码和查询日志不裸奔，可以在反向代理上做 HTTPS。以 Caddy 为例，在能解析到该域名的内网 DNS 或 hosts 中配置：

adguard.example.com {
    reverse_proxy 127.0.0.1:3000
}

然后把 AdGuard Home 的管理监听地址改为 127.0.0.1:3000，Docker 端口映射也改为 127.0.0.1:3000:3000，只让反向代理访问。证书可以用 Let’s Encrypt DNS-01，也可以使用内网 CA。不要把 3000 和 53 直接映射到公网，开放式 DNS resolver 很容易被拿来做放大攻击。

九、备份、更新与日常维护#

需要备份的核心是配置目录里的 AdGuardHome.yaml，以及 work 目录中的统计和查询数据。最稳妥的方式是停止容器后打包两个目录：

docker stop adguardhome
sudo tar czf adguardhome-backup-$(date +%F).tar.gz \
  -C /opt/adguardhome work conf
docker start adguardhome

Docker 部署不支持在网页里自动更新，需要拉取新镜像并重建容器：

docker pull adguard/adguardhome
docker stop adguardhome
docker rm adguardhome
# 使用前面的 docker run 或 docker compose up -d 重新启动

建议把查询日志保留时间设为 24 小时到 7 天，统计保留时间也控制在一周左右。家庭环境没有必要保存几个月日志；磁盘写满后，AdGuard Home 的统计和配置写入都会受影响。

十、常见问题排查#

十一、安全设置别省略#

• 管理后台使用强密码，不要暴露在公网；需要远程管理时优先使用 VPN 或只允许内网访问。
• 不要在公网开放 53、3000、80、443 等不必要的端口；DNS 服务尤其要避免成为开放 resolver。
• 在「设置 → 客户端」中按需限制允许查询的网段，减少被滥用的可能。
• 开启 DNSSEC（如果上游支持），并保持 AdGuard Home 镜像更新。
• 改路由器 DNS 前保留回滚方法：记下原 DNS，出现故障时能立刻改回。

十二、总结#

AdGuard Home 的价值不只是“去广告”，而是把家庭网络的 DNS 解析、加密上游、过滤规则、客户端统计和查询日志集中到一个面板里。部署时真正容易出问题的通常不是镜像，而是 53 端口、IPv6 DNS、路由器回环和上游配置。按“先单机测试、再改路由器、最后加规则”的顺序推进，排错成本会低很多。

参考资料#

• AdGuard Home 官方 GitHub 仓库
• AdGuard Home 官方 Overview
• AdGuard Home Getting started
• AdGuard Home Docker 文档
• CSDN：AdGuard Home 全屋去广告教程
• 知乎：AdGuard Home 相关实践

版权声明#

本文由 砂糖橘猫 创作，首发于 www.luna.tel，采用 知识共享署名 4.0 国际许可协议（CC BY 4.0） 授权。转载请注明作者、原文链接，并保留本版权声明。

CC BY 4.0