AdGuard Home 项目部署

项目定位：全网络范围的 DNS 广告与追踪器拦截软件，也是一个可自托管的 DNS 服务器。部署在家庭网络或服务器后，局域网内所有设备不需要逐个安装客户端即可享受广告拦截、隐私保护与家长控制。
主要语言：Go，内置网页管理界面
开源协议：GPL-3.0
文档依据：项目仓库说明与社区部署指南（2026 年 11 月），具体参数以官方最新文档为准。

一、功能与原理

AdGuard Home 工作在 DNS 层：设备要访问某个域名时先向它查询，如果该域名在过滤列表中（广告、追踪、恶意网站），就直接返回拦截结果，页面上的广告也就加载不出来。

能力边界（务必了解）：

• DNS 层拦截无法处理「广告与正文来自同一域名」的情况，例如部分视频网站和应用内的第一方广告。
• 它不能替代浏览器里的内容拦截扩展，两者可以搭配使用。
• 一旦 DNS 服务异常，全家上网都会受影响，建议规划备用 DNS。

二、部署方案选择

本文以 Docker Compose 为主，并补充二进制部署。

三、环境要求

• 一台常开的 Linux 设备或服务器（树莓派、NAS、软路由、小型 VPS 均可）
• 内存 512MB 以上，磁盘 1GB 以上（日志越多占用越大）
• Docker Engine 与 Docker Compose 插件
• 53 端口未被占用（这是最常见的坑，见下一节）
• 固定的内网 IP 地址（作为 DNS 服务器地址，建议在路由器中做静态绑定）

3.1 处理 53 端口冲突（以 Ubuntu 为例）

Ubuntu 默认的 systemd-resolved 会占用 53 端口，导致 AdGuard Home 启动失败。先检查：

sudo ss -lntup | grep ':53 '

如果看到被 systemd-resolved 占用，可以关闭它的本地监听：

sudo mkdir -p /etc/systemd/resolved.conf.d
sudo tee /etc/systemd/resolved.conf.d/adguardhome.conf << 'CONF'
[Resolve]
DNS=127.0.0.1
DNSStubListener=no
CONF
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

注意：修改后宿主机自身的解析依赖 AdGuard Home 或上游 DNS，操作前确认有控制台访问方式，避免把自己锁在外面。

四、Docker Compose 部署

4.1 创建目录

mkdir -p ~/adguard-home/{conf,work}
cd ~/adguard-home

目录说明：

• conf：配置文件目录，核心文件是 AdGuardHome.yaml
• work：工作目录，保存查询日志、统计数据和下载的过滤列表

4.2 编写 docker-compose.yml（端口映射模式）

适用于只做 DNS 过滤、不接管 DHCP 的常见场景：

services:
  adguardhome:
    image: adguard/adguardhome:latest
    container_name: adguardhome
    restart: unless-stopped
    ports:
      - "53:53/tcp"       # DNS
      - "53:53/udp"       # DNS
      - "3000:3000/tcp"   # 首次安装向导（初始化完成后可去掉）
      - "80:80/tcp"       # 管理界面（可改为其他端口）
      - "443:443/tcp"     # DoH（需要配置证书）
      - "443:443/udp"     # DoH over HTTP/3
      - "853:853/tcp"     # DoT（需要配置证书）
      - "853:853/udp"     # DoQ（需要配置证书）
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf

说明：

• 只在内网使用时，可以只保留 53、3000 和管理界面端口，加密 DNS 相关端口在配好证书后再开放。
• 管理界面如果要换端口（例如 8080），请同时修改映射和初始化向导里的网页端口设置。
• 生产环境建议把镜像固定到具体版本号，按需升级。

4.3 需要接管 DHCP 时（主机网络模式）

DHCP 依赖广播，端口映射下无法正常工作。若希望用 AdGuard Home 替代路由器的 DHCP，在 Linux 上使用主机网络模式，并去掉 ports 配置：

services:
  adguardhome:
    image: adguard/adguardhome:latest
    container_name: adguardhome
    restart: unless-stopped
    network_mode: host
    cap_add:
      - NET_ADMIN
    volumes:
      - ./work:/opt/adguardhome/work
      - ./conf:/opt/adguardhome/conf

提醒：同一网段内只能有一个 DHCP 服务器，启用前务必先在路由器中关闭它的 DHCP，否则会产生冲突。多数家庭场景保留路由器 DHCP 并把 DNS 指向 AdGuard Home 即可，更稳妥。

4.4 启动

docker compose up -d
docker compose ps
docker compose logs -f adguardhome

五、初始化向导

1. 浏览器访问「服务器IP地址:3000」，进入安装向导。
2. 设置管理界面的监听地址和端口（默认 80），以及 DNS 服务监听端口（默认 53）。
3. 创建管理员用户名和密码，使用强密码。
4. 完成后进入管理后台。以后用「服务器IP地址」加你设置的端口访问。

向导完成后，若不再需要，可以从 Compose 中移除 3000 端口映射并重新应用。

六、基础配置

6.1 上游 DNS

在「设置 → DNS 设置」中配置：

• 上游服务器：可选择加密上游（DoH、DoT），选择你网络环境下速度和稳定性较好的服务商，可填写多个并选择并行请求或最快响应。
• 引导 DNS：用来解析加密上游的域名，填写普通 DNS 地址即可。
• 回退 DNS：上游全部失败时使用，建议配置。

6.2 过滤列表

在「过滤器 → DNS 封锁清单」中添加。内置的 AdGuard DNS 过滤器是常见起点，可再按需添加其他社区列表（针对广告、追踪、恶意网站、特定地区）。

建议：

• 列表不要贪多，过多会增加误拦截并占用内存。
• 出现网站或应用异常时，到查询日志里确认是否被拦截，再加入白名单规则。

6.3 让全网设备使用 AdGuard Home

有两种做法，推荐第一种：

1. 在路由器里修改 DHCP 下发的 DNS：把主 DNS 设置为 AdGuard Home 所在设备的内网 IP，所有设备自动生效。
2. 逐设备手动设置 DNS：适合只想让部分设备使用的场景。

配置完成后，到管理后台首页观察查询数是否在增长，并用设备访问带广告的页面验证。

6.4 DNS 重写

在「过滤器 → DNS 重写」中，可以把内网域名指向内网 IP，例如给 NAS、各类自托管服务起统一的名字，访问更方便。

七、启用加密 DNS 与 HTTPS（可选）

适用于希望在外网通过 DoH、DoT 使用自己的 DNS，或给管理界面启用 HTTPS 的场景。

1. 准备域名，并解析到服务器公网 IP。
2. 获得受信任的证书（可用 ACME 工具签发），把证书与私钥放到容器可读取的路径，并挂载进容器。
3. 在「设置 → 加密设置」中启用加密，填写服务器名称、证书和私钥路径。
4. 放行对应端口：DoT 使用 853，DoH 使用 443，DoQ 使用 UDP 853（具体以后台提示为准）。
5. 客户端侧使用域名配置 DoH 或 DoT 地址。

安全提醒：

• 不要把未做访问控制的 DNS 服务暴露到公网，否则可能被滥用为 DNS 放大攻击的跳板。
• 在「设置 → DNS 设置 → 访问设置」中配置允许的客户端或域名名单，只允许自己的设备使用。

八、二进制部署（不使用 Docker）

1. 在项目的发布页面下载与你系统架构匹配的压缩包，解压到 /opt 之类的固定目录。
2. 进入解压后的 AdGuardHome 目录，注册并启动为系统服务：

sudo ./AdGuardHome -s install
sudo ./AdGuardHome -s status

3. 之后同样通过「服务器IP地址:3000」完成初始化向导。
4. 常用服务管理命令：

sudo ./AdGuardHome -s start
sudo ./AdGuardHome -s stop
sudo ./AdGuardHome -s restart
sudo ./AdGuardHome -s uninstall

升级可使用后台里的在线更新，或先停止服务、替换二进制后再启动。

九、备份、升级与维护

9.1 备份

• 核心备份对象是配置文件 AdGuardHome.yaml（位于 conf 目录），其中包含全部设置、客户端、规则与用户信息。
• 如需保留统计与查询日志，则备份 work 目录。
• 备份文件含有账号哈希与规则，请妥善保存，不要公开上传。

9.2 升级（Docker）

cd ~/adguard-home
docker compose pull
docker compose up -d
docker image prune

容器内的在线更新可能在重启后被重置，使用 Docker 时应以更新镜像为准。配置与数据保存在挂载目录中，升级不会丢失。

9.3 日常维护

• 在设置里合理配置查询日志保留时间与统计保留时间，避免占用过多磁盘。
• 定期更新过滤列表（默认自动更新），并检查是否有误拦截。
• 为 AdGuard Home 所在设备设置静态 IP，并在路由器中配置备用 DNS，防止单点故障导致全网无法解析。

十、常见问题排查

十一、命令速查

# 启动 / 停止 / 重启
docker compose up -d
docker compose down
docker compose restart adguardhome

# 查看状态与日志
docker compose ps
docker compose logs -f adguardhome

# 升级
docker compose pull && docker compose up -d

# 检查 53 端口占用
sudo ss -lntup | grep ':53 '

# 测试解析（把地址换成你的 AdGuard Home 内网 IP）
nslookup example.org 192.168.1.2