如何在 Ubuntu 24.04 上安装和使用 AdGuard

拦截网络广告（ads）的方法有很多种。其中最流行的一种是使用浏览器扩展。但如果你想拦截其他应用甚至手机游戏中的广告，该怎么办呢？在这种情况下，你需要从源头——也就是直接在网络层面上——来拦截广告。这就是 AdGuard 发挥作用的地方。通过让 AdGuard 充当一个过滤你的网络与互联网之间内容的中间人（一个 DNS 服务器），你可以拦截所有或大部分广告。

在本文中，你将在 Ubuntu 24.04 上安装并设置 AdGuard Home，启用带有自动续期的 TLS 加密，并配置自定义 DNS 设置。你可以选择两种安装方法：使用 Docker 或官方安装脚本。

准备

• 一台云服务器

如果没有，可以前往 雨云- 新一代云服务提供商 进行注册，新用户有五折优惠。

全产品线路优化：

1. 香港CN2三网直连，延迟低至35ms；
2. 美国（CMI+9929）,延迟低至140ms；
3. 日本东京三网直连，延迟低至60ms；

更有国内：浙江宁波、广东深圳、广东广州、湖北襄阳、江苏宿迁、重庆电信 地区服务器，价格平民，质量优质，CPU强劲。

拥有：云应用、云服务器、游戏云、显卡云、对象存储、裸金属物理机、域名服务、SSL证书、虚拟主机、雨盾CDN 产品！

新用户更有五折券优惠，支持一元试用！点击进行注册

---

前提条件

在开始之前，请确保：

• 拥有一台基于 Ubuntu 24.04 的服务器，并能以拥有 sudo 权限的非 root 用户身份登录。
• 在你的域名 DNS 中创建一条 A 记录，指向你的服务器 IP 地址。本文使用 adguard.example.com 作为示例，请替换为你自己的域名。

理解 AdGuard Home 的工作原理

AdGuard Home 是一个能在你的整个网络范围内拦截广告和恶意域名的工具。它的工作原理是充当你的 DNS 服务器。当网络中的设备尝试访问互联网时，AdGuard 会检查请求的域名是否在黑名单上。如果在，AdGuard 会阻止连接，并通过返回一个假的 IP 地址来防止广告或跟踪器加载。

与只在单个设备上拦截广告的浏览器扩展不同，AdGuard 过滤来自连接到你网络中每一台设备的所有 DNS 流量。它还通过加密 DNS 等功能，保护你的互联网活动不被你的互联网服务提供商窥探。

从 systemd-resolved 释放 53 端口

Ubuntu 24.04 默认使用 systemd-resolved进行本地 DNS 缓存和解析，该服务默认绑定到 53 端口。而 AdGuard Home 需要这个端口来提供 DNS 服务。请按照以下步骤重新配置 systemd-resolved 并释放 53 端口。

1. 创建 /etc/systemd/resolved.conf.d 目录以存放新的配置文件。

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

2. 创建并编辑新的配置文件 /etc/systemd/resolved.conf.d/adguardhome.conf。

   $ sudo nano /etc/systemd/resolved.conf.d/adguardhome.conf
   

   创建新的配置文件而不是编辑现有文件，可以确保在系统升级时这些更改不会被覆盖。

3. 将以下内容添加到文件中。

   [Resolve]
   DNS=127.0.0.1
   DNSStubListener=no
   

   保存并关闭文件。以上配置：

   • 明确将 DNS 设置为 127.0.0.1，也就是 AdGuard Home。
   • 禁用 DNSStubListener，从而释放 53 端口。

4. /etc/resolv.conf 是大多数程序用来确定使用哪个 DNS 服务器的文件。该文件是一个指向 /run/systemd/resolve/stub-resolv.conf 的符号链接，后者指向 127.0.0.53。禁用 DNSStubListener 后，此配置会失效。你需要更新这个符号链接：

   1. 备份现有的 resolv.conf 文件。

      $ sudo mv /etc/resolv.conf /etc/resolv.conf.backup
      

   2. 创建一个新的符号链接，指向 /run/systemd/resolve/resolv.conf。

      $ sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf
      

      这一步确保应用程序现在使用在 adguardhome.conf 中定义的 DNS 服务器。文件 /run/systemd/resolve/resolv.conf 会动态反映 systemd-resolved 的活动解析器设置，包括你在 /etc/systemd/resolved.conf.d/adguardhome.conf 中添加的覆盖配置。现在，所有 DNS 查询都将被重定向到 127.0.0.1，即 AdGuard Home 正在监听的地址。

   3. 重启 systemd-resolved 以应用更改。

      $ sudo systemctl restart systemd-resolved
      

5. 验证 53 端口是否已被释放。

   $ sudo lsof -i :53
   

   该命令应该没有任何输出。

设置防火墙规则

在安装和配置 AdGuard Home 之前，配置 UFW 以允许连接到所需的端口。

1. 允许 53 端口上的 DNS 流量。

   $ sudo ufw allow 53
   

2. 允许 DNS-over-TLS 和 DNS-over-QUIC 使用的 853 端口。

   $ sudo ufw allow 853
   

   DNS-over-TLS 使用 TCP 协议，而 DNS-over-QUIC 使用 UDP 协议。

3. AdGuard Home 的初始设置界面运行在 3000 端口，请允许它。

   $ sudo ufw allow 3000/tcp
   

4. 允许用于 Web 仪表盘和证书验证的 HTTP 流量。

   $ sudo ufw allow 80/tcp
   

5. 允许用于安全 Web 界面和启用 DNS-over-HTTPS 的 HTTPS 流量。

   $ sudo ufw allow 443/tcp
   

6. 重新加载 UFW 以应用防火墙规则。

   $ sudo ufw reload
   

在 Ubuntu 24.04 上安装 AdGuard Home

你可以使用 Docker 或官方安装脚本来安装 AdGuard Home。两种方法都提供相同的功能。

使用 Docker 安装

1. 在你的服务器上安装 Docker。
2. 将你的用户添加到 Docker 组。

   $ sudo usermod -aG docker $USER
   

3. 更新 Docker 组成员身份。

   $ newgrp docker
   

4. 创建项目目录结构。

   $ mkdir -p ~/adguardhome/{conf,work,certs,scripts}
   

5. 导航到项目根路径。

   $ cd ~/adguardhome
   

6. 创建一个 Docker Compose 配置文件。

   $ nano compose.yml
   

7. 添加以下配置。

   name: adguardhome
   
   services:
     adguardhome:
       image: adguard/adguardhome:latest
       container_name: adguardhome
       network_mode: host
       restart: unless-stopped
       volumes:
         - ./conf:/opt/adguardhome/conf
         - ./work:/opt/adguardhome/work
         - ./certs:/opt/adguardhome/certs
       cap_add:
         - NET_ADMIN
         - NET_BIND_SERVICE
         - NET_RAW
       healthcheck:
         test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000"]
         interval: 30s
         timeout: 10s
         retries: 3
         start_period: 40s
   

   保存并关闭文件。此文件定义了：
   • 一个名为 adguardhome 的服务，使用官方的 adguard/adguardhome:latest 镜像。
   • network_mode: host 使容器共享主机的网络栈，可以直接绑定到 DNS 53 端口。
   • 卷 (conf, work, certs) 用于在容器重启后持久化配置、运行时数据和证书。
   • 附加的 Linux 能力 (NET_ADMIN, NET_BIND_SERVICE, NET_RAW) 允许容器处理底层网络操作并绑定到特权端口。
   • 一个健康检查，它会查询 3000 端口上的 Web 设置界面以验证服务是否正在运行。
8. 启动 AdGuard Home 容器。

   $ docker compose up -d
   

   此命令会：
   • 从 Docker Hub 拉取 AdGuard Home 镜像。
   • 以分离模式创建并启动容器。
9. 验证容器是否正在运行。

   $ docker compose ps
   

使用 AdGuard Home 安装脚本安装

此方法使用 AdGuard Home 的官方安装脚本，将应用程序作为系统服务在你的主机上运行。按照以下步骤使用安装脚本安装 AdGuard Home。

1. 更新你的系统。

   $ sudo apt update
   

2. 下载并运行 AdGuard Home 安装脚本。

   $ curl -s -S -L https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh | sh -s -- -v
   

3. 创建用于存放证书和脚本的目录。

   $ sudo mkdir -p /opt/AdGuardHome/{certs,scripts}
   

4. 验证 AdGuard Home 服务状态。

   $ sudo /opt/AdGuardHome/AdGuardHome -s status
   

   输出应包含一行指示服务正在运行的内容，类似于：

   ...
   2025/10/07 17:37:00 [info] service: running
   ...
   

生成 TLS 证书

本节将介绍如何生成 Let’s Encrypt 证书，以实现对 AdGuard Home 仪表盘的安全 HTTPS 访问。

1. 安装 Certbot 用于生成证书。

   $ sudo apt install certbot -y
   

2. 为你的域名生成证书。请将 adguard.example.com 替换为你的实际域名，并将 admin@example.com 替换为你的电子邮件地址。

   $ sudo certbot certonly --standalone -d adguard.example.com --agree-tos --no-eff-email --email admin@example.com
   

   输出：

   ...
   Successfully received certificate.
   Certificate is saved at: /etc/letsencrypt/live/adguard.example.com/fullchain.pem
   Key is saved at:         /etc/letsencrypt/live/adguard.example.com/privkey.pem
   ...
   

3. 根据你的安装方法创建一个证书复制脚本。

   • 对于 Docker 安装：

     $ nano ~/adguardhome/scripts/copy-certs.sh
     

   • 对于脚本安装：

     $ sudo nano /opt/AdGuardHome/scripts/copy-certs.sh
     

4. 添加证书复制脚本内容。请将 adguard.example.com 替换为你的实际域名。

   • 对于 Docker 安装：

     #!/bin/bash
     
     DOMAIN="adguard.example.com"
     ADGUARD_DIR="/home/YOUR_USERNAME/adguardhome"
     CERT_DIR="$ADGUARD_DIR/certs"
     
     sudo cp /etc/letsencrypt/live/$DOMAIN/fullchain.pem $CERT_DIR/cert.pem
     sudo cp /etc/letsencrypt/live/$DOMAIN/privkey.pem $CERT_DIR/key.pem
     sudo chown YOUR_USERNAME:YOUR_USERNAME $CERT_DIR/*.pem
     chmod 644 $CERT_DIR/cert.pem
     chmod 600 $CERT_DIR/key.pem
     
     if docker ps | grep -q adguardhome; then
         cd $ADGUARD_DIR
         docker compose restart
     fi
     

     保存并关闭文件。然后，用你的实际用户名更新脚本。将所有 YOUR_USERNAME 替换为你的系统用户名。

     $ sed -i "s/YOUR_USERNAME/$USER/g" ~/adguardhome/scripts/copy-certs.sh
     

   • 对于脚本安装，添加以下内容：

     #!/bin/bash
     
     DOMAIN="adguard.example.com"
     CERT_DIR="/opt/AdGuardHome/certs"
     
     cp /etc/letsencrypt/live/$DOMAIN/fullchain.pem $CERT_DIR/cert.pem
     cp /etc/letsencrypt/live/$DOMAIN/privkey.pem $CERT_DIR/key.pem
     chmod 644 $CERT_DIR/cert.pem
     chmod 600 $CERT_DIR/key.pem
     
     /opt/AdGuardHome/AdGuardHome -s restart
     

5. 使脚本可执行并运行它。

   • 对于 Docker 安装：

     $ chmod +x ~/adguardhome/scripts/copy-certs.sh
     $ ~/adguardhome/scripts/copy-certs.sh
     

   • 对于脚本安装：

     $ sudo chmod +x /opt/AdGuardHome/scripts/copy-certs.sh
     $ sudo /opt/AdGuardHome/scripts/copy-certs.sh
     

6. 检查证书。

   • 对于 Docker：

     $ ls -la ~/adguardhome/certs/
     

   • 对于脚本安装：

     $ sudo ls -la /opt/AdGuardHome/certs/
     

   你应该能看到具有正确权限的 cert.pem 和 key.pem 文件。

配置自动证书续期

Let’s Encrypt 证书每 90 天过期一次。在本节中，你将配置 TLS 证书的自动续期。

1. 创建一个 Certbot 续期钩子脚本。

   $ sudo nano /etc/letsencrypt/renewal-hooks/deploy/adguard-renewal.sh
   

2. 根据你的安装方法添加续期脚本内容。

   • 对于 Docker 安装：

     #!/bin/bash
     /home/YOUR_USERNAME/adguardhome/scripts/copy-certs.sh
     

     注意
     请将 YOUR_USERNAME 替换为你的用户名。

   • 对于脚本安装：

     #!/bin/bash
     /opt/AdGuardHome/scripts/copy-certs.sh
     

   保存并关闭文件。

3. 使续期钩子可执行。

   $ sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/adguard-renewal.sh
   

4. 为了处理续期期间 80 端口的冲突（因为 AdGuard Home 设置后会绑定 80 端口），创建停止和启动脚本，然后将 pre-hooks 和 post-hooks 添加到 Certbot 续期配置中。这会在续期尝试前临时停止 AdGuard Home，并在之后启动它。

   • 对于 Docker 安装：

     1. 创建一个停止脚本。

        $ nano ~/adguardhome/scripts/stop-adguard.sh
        

        添加：

        #!/bin/bash
        docker compose -f /home/YOUR_USERNAME/adguardhome/compose.yml stop > /dev/null 2>&1
        

     2. 创建一个启动脚本。

        $ nano ~/adguardhome/scripts/start-adguard.sh
        

        添加：

        #!/bin/bash
        docker compose -f /home/YOUR_USERNAME/adguardhome/compose.yml start > /dev/null 2>&1
        

     3. 使它们可执行。

        $ chmod +x ~/adguardhome/scripts/{stop-adguard.sh,start-adguard.sh}
        

     4. 用你的实际用户名更新脚本。

        $ sed -i "s/YOUR_USERNAME/$USER/g" ~/adguardhome/scripts/stop-adguard.sh
        $ sed -i "s/YOUR_USERNAME/$USER/g" ~/adguardhome/scripts/start-adguard.sh
        

   • 对于脚本安装：

     1. 创建一个停止脚本。

        $ sudo nano /opt/AdGuardHome/scripts/stop-adguard.sh
        

        添加：

        #!/bin/bash
        /opt/AdGuardHome/AdGuardHome -s stop > /dev/null 2>&1
        

     2. 创建一个启动脚本。

        $ sudo nano /opt/AdGuardHome/scripts/start-adguard.sh
        

        添加：

        #!/bin/bash
        /opt/AdGuardHome/AdGuardHome -s start > /dev/null 2>&1
        

     3. 使它们可执行。

        $ sudo chmod +x /opt/AdGuardHome/scripts/{stop-adguard.sh,start-adguard.sh}
        

5. 编辑 Certbot 续期配置以添加钩子。将 adguard.example.com 替换为你的域名。

   $ sudo nano /etc/letsencrypt/renewal/adguard.example.com.conf
   

   在 [renewalparams] 部分下添加或更新：

   • 对于 Docker 安装：

     pre_hook = /home/YOUR_USERNAME/adguardhome/scripts/stop-adguard.sh
     post_hook = /home/YOUR_USERNAME/adguardhome/scripts/start-adguard.sh
     

     注意
     请将 YOUR_USERNAME 替换为你的用户名。

   • 对于脚本安装：

     pre_hook = /opt/AdGuardHome/scripts/stop-adguard.sh
     post_hook = /opt/AdGuardHome/scripts/start-adguard.sh
     

   保存并关闭文件。

6. 测试自动续期过程。

   $ sudo certbot renew --dry-run
   

   输出：

   ...
   Congratulations, all simulated renewals succeeded
   ...
   

配置 AdGuard Home 的初始设置

访问 AdGuard Home 的 Web 界面以完成初始配置。

1. 打开你的 Web 浏览器并导航到设置界面。

   http://你的服务器IP:3000
   

2. 在欢迎页面上点击 Get Started。

3. 设置管理员 Web 界面：

   • Listen Interface: 选择 All interfaces
   • Port: 输入 80

4. 配置 DNS 服务器：

   • Listen Interface: 选择 All interfaces
   • Port: 保持 53

5. 点击 Next 并创建一个带有用户名和强密码的管理员账户。

6. 点击 Next。你将进入 Configure your devices 页面，这里会显示各种设备的配置设置。点击 Next。

7. 点击 Open Dashboard 访问主界面。

8. 完成初始配置后，从防火墙中移除 3000 端口。

   $ sudo ufw delete allow 3000/tcp
   $ sudo ufw reload
   

启用 TLS 加密

使用你的 TLS 证书配置 HTTPS 访问，以实现安全的仪表盘访问。

1. 访问 AdGuard Home 仪表盘并使用你之前设置的凭据登录。

   http://你的服务器IP
   

   

2. 点击顶部导航菜单上的 Settings 按钮，然后点击 Encryption settings。

   

3. 配置以下加密设置：

   • Enable Encryption: 勾选以启用。
   • Server name: 输入你的域名。
   • Redirect to HTTPS automatically: 启用。
   • HTTPS port: 443
   • DNS-over-HTTPS port: 443
   • DNS-over-TLS port: 853
   • DNS-over-QUIC port: 853

   

4. 配置证书路径：

   • 选择 Set a certificates file path 选项。
   • 对于 Docker 安装：
     • Certificates path: /opt/adguardhome/certs/cert.pem
     • Private key path: /opt/adguardhome/certs/key.pem
   • 对于脚本安装：
     • Certificates path: /opt/AdGuardHome/certs/cert.pem
     • Private key path: /opt/AdGuardHome/certs/key.pem

5. 点击 Save 以应用加密设置。启用加密后，请使用 https://adguard.example.com 访问 AdGuard Home。

配置 DNS 隐私设置

AdGuard Home 支持加密的 DNS 协议，以防止 ISP 和第三方监控你的 DNS 查询。配置支持 DNS-over-HTTPS (DoH) 或 DNS-over-TLS (DoT) 的上游 DNS 服务器以增强隐私。

1. 点击顶部导航菜单上的 Settings 按钮，然后点击 DNS Settings。

2. 在 Upstream DNS servers 字段中，添加你选择的加密 DNS 提供商，例如：

   https://dns.cloudflare.com/dns-query
   https://dns.google/dns-query
   https://dns.quad9.net/dns-query
   tls://1.1.1.1
   tls://8.8.8.8
   

   这些上游服务器使用 HTTPS 或 TLS 加密来保护 AdGuard Home 和上游提供商之间的 DNS 查询。加密协议可以防止你的 ISP 看到你正在解析哪些域名。

3. 配置 Fallback DNS servers 以实现冗余。当加密的上游服务器不可用时，将使用这些服务器。添加你选择的 DNS 服务器，例如：

   1.1.1.1
   8.8.8.8
   9.9.9.9
   

   注意
   备用服务器通常使用标准的未加密 DNS（端口 53），因为它们在加密连接失败时充当紧急备份。在正常操作期间，AdGuard Home 仅使用加密的上游服务器。

4. 配置 Bootstrap DNS servers。这些服务器用于解析你的加密上游服务器的域名（如 dns.cloudflare.com）。你可以添加：

   1.1.1.1
   8.8.8.8
   9.9.9.9
   

5. 启用以下 DNS 功能：

   • Parallel requests: 启用以同时查询多个服务器，以获得更快的响应。
   • Enable DNSSEC: 验证 DNS 响应的真实性。
   • Enable EDNS client subnet: 提高 CDN 性能。
   • Disable IPv6: 仅在你的网络不支持 IPv6 时启用。

6. 点击 Save 以应用 DNS 配置。

设置黑名单

AdGuard 有一个内置的 DNS 过滤器，但你可以通过添加额外的黑名单来扩展其功能。这些公开维护的列表包含数以万计的已知广告、跟踪器、恶意软件和遥测域名。

1. 从顶部导航菜单中，点击 Filters 并选择 DNS blocklists。

   

2. 点击 Add blocklist 并点击 Choose from the list。

3. 选择下图中的选项，然后点击 Save。

   

4. 浏览一会儿互联网，然后在浏览器中检查你的 AdGuard Home 仪表盘。

   http://SERVER-IP
   

   你应该能看到所有被拦截的网站、跟踪器和广告。

自定义 DNS 重写

DNS 重写是覆盖标准 DNS 解析的规则，通过将特定的域名映射到自定义 IP 地址来实现。AdGuard 支持 DNS 重写，允许你在网络内部将域名映射到特定的 IP 地址。这就像一个用于内部使用的迷你本地 DNS 服务器。例如，你可以将 adguard.home 映射到 SERVER-IP，以便访问你的 AdGuard 仪表盘。按照以下步骤，使用 adguard.home 而不是你的服务器 IP 地址来访问你的 AdGuard Home 仪表盘。

1. 从顶部导航菜单中，点击 Filters 并选择 DNS rewrites。

2. 点击 Add DNS rewrites。

3. 输入域名和你的服务器 IP 地址，然后点击 Save。

   

配置客户端设备

你可以配置你的设备以使用 AdGuard Home 作为其 DNS 服务器。不同类型的设备配置方式有所不同。以下部分将介绍如何设置你的路由器以使用你的 AdGuard Home 服务器作为 DNS 服务器。

路由器配置

配置你的路由器，以便自动为所有连接的设备应用 AdGuard Home DNS。

1. 访问你的路由器的管理网页（通常是 http://192.168.1.1 或 http://192.168.0.1）。
2. 导航到 DHCP 或 DNS 设置部分。
3. 启用自定义 DNS 并添加你的 AdGuard Home 服务器的 IP 地址，或者用你的 AdGuard Home 服务器的 IP 地址替换现有的 DNS 服务器地址。
4. 保存并应用设置。

你可以在 AdGuard Home 仪表盘顶部导航菜单的 Setup Guide 选项中找到大多数设备类型的配置设置。

监控与维护

AdGuard Home 在其仪表盘上显示有关 DNS 查询的统计信息。

查看统计信息

访问仪表盘 https://adguard.example.com。你应该能看到到达你的 AdGuard Home DNS 服务器的 DNS 查询日志。

结论

你已经成功在 Ubuntu 24.04 上部署了 AdGuard Home，并使用官方安装脚本和 Docker 实现了自动 TLS 证书续期和加密 DNS 协议。要了解更多关于其用法的信息，请参阅 AdGuard Home Wiki 页面。