家庭网络级解决方案:AdguardHome

阿呆2025-02-262025-11-01

在 Debian 系统上搭建 AdGuard Home 的完整教程

环境准备

1. 系统要求

操作系统: Linux系统
硬件要求: AdGuard Home 对内存和 CPU 要求较低，适合在小型设备（如树莓派）上运行。
网络要求: 公网 IP（可选，用于远程管理）

2. 更新系统包

1	sudo apt update && sudo apt upgrade -y

部署 AdGuard Home

1. 下载 AdGuard Home

1. 选择自动安装方式

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

1	wget --no-verbose -O - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh \| sh -s -- -v

1	fetch -o - https://raw.githubusercontent.com/AdguardTeam/AdGuardHome/master/scripts/install.sh \| sh -s -- -v

2. 如果系统启用防火墙，需手动开放端口：

DNS 监听端口（默认 53）和 HTTP 管理端口（默认 3000）

1 2	sudo ufw allow 53 sudo ufw allow 3000/tcp

安装docker

拉取 Docker 镜像
1
docker pull adguard/adguardhome

创建并运行容器

docker run --name adguardhome\
    --restart unless-stopped\
    -v /my/own/workdir:/opt/adguardhome/work\
    -v /my/own/confdir:/opt/adguardhome/conf\
    -p 53:53/tcp -p 53:53/udp\
    -p 67:67/udp -p 68:68/udp\
    -p 80:80/tcp -p 443:443/tcp -p 443:443/udp -p 3000:3000/tcp\
    -p 853:853/tcp\
    -p 853:853/udp\
    -p 5443:5443/tcp -p 5443:5443/udp\
    -p 6060:6060/tcp\
    -d adguard/adguardhome

# 参数说明
--name adguardhome \  #指定容器名称为 adguardhome，方便后续通过名称管理容器（如启动、停止、删除等）
--restart unless-stopped \  #设置容器重启策略：除非手动停止，否则容器退出时自动重启（确保服务持续运行）
-v /my/own/workdir:/opt/adguardhome/work \ #挂载主机目录到容器工作目录：主机目录 /my/own/workdir <-> 容器内 /opt/adguardhome/work 用于持久化存储 AdGuard Home 的工作数据（如过滤规则、查询日志、缓存等）
-v /my/own/confdir:/opt/adguardhome/conf \ #挂载主机目录到容器配置目录：主机目录 /my/own/confdir <-> 容器内 /opt/adguardhome/conf 用于持久化存储配置文件（如 AdGuardHome.yaml），避免容器删除后配置丢失
-p 53:53/tcp -p 53:53/udp \ #映射 DNS 服务端口（TCP+UDP）：主机 53 端口 <-> 容器 53 端口 53 是 DNS 协议默认端口，AdGuard Home 作为 DNS 服务器需监听此端口处理域名解析请求
-p 67:67/udp -p 68:68/udp \ #映射 DHCP 服务端口（UDP）：主机 67/68 端口 <-> 容器 67/68 端口 67 是 DHCP 服务器端口，68 是 DHCP 客户端端口，启用 AdGuard Home 的 DHCP 功能时需要
-p 80:80/tcp \ #映射 HTTP 端口（TCP）：主机 80 端口 <-> 容器 80 端口 用于处理 HTTP 请求（如 Web 管理界面的 HTTP 访问、广告过滤的 HTTP 请求拦截等）
-p 443:443/tcp -p 443:443/udp \ #映射 HTTPS 及相关加密端口（TCP+UDP）：主机 443 端口 <-> 容器 443 端口 TCP 用于 HTTPS 协议（Web 管理界面的 HTTPS 访问），UDP 可能用于 DNS-over-HTTPS（DoH）等加密通信
-p 3000:3000/tcp \ #映射初始配置界面端口（TCP）：主机 3000 端口 <-> 容器 3000 端口 首次启动 AdGuard Home 时，通过此端口访问初始化配置界面（如设置管理员账号、DNS 上游等）
-p 853:853/tcp -p 853:853/udp \ #映射 DNS-over-TLS/QUIC 端口（TCP+UDP）：主机 853 端口 <-> 容器 853 端口 853 是 DNS-over-TLS（DoT）的标准端口（TCP），同时也用于 DNS-over-QUIC（DoQ）（UDP，符合 RFC 规范）
-p 5443:5443/tcp -p 5443:5443/udp \ #映射备用加密服务端口（TCP+UDP）：主机 5443 端口 <-> 容器 5443 端口 常用于 DNS-over-HTTPS（DoH）的备用端口，或其他加密管理服务
-p 6060:6060/tcp \ #映射性能分析端口（TCP）：主机 6060 端口 <-> 容器 6060 端口 对应配置中 pprof.port，用于 AdGuard Home 的性能分析和调试（如 Go 语言的 pprof 工具）
-d adguard/adguardhome -d #表示后台运行容器；adguard/adguardhome 是使用的 Docker 镜像名称

控制指令

启动

1	docker start adguardhome

停止

1	docker stop adguardhome

删除

1	docker rm adguardhome

安装docker和Docker-Composr
1
mkdir adguardhome && cd adguardhome
创建 docker-compose.yml
1
nano docker-compose.yml

编写docker-compose.ymlCtrl + X按Y，Enter保存

version: '3'  # 指定Docker Compose文件格式版本（v3兼容大多数现代Docker环境）

services:
  adguardhome:  # 定义服务名称为adguardhome
    image: adguard/adguardhome:latest  # 使用AdGuard Home官方最新镜像
    container_name: adguardhome  # 指定容器名称，便于通过名称管理（如启动、停止）
    restart: unless-stopped  # 容器重启策略：除非手动停止，否则退出后自动重启（保证服务持续运行）
    # 使用命名卷存储数据，无需手动创建主机目录，由Docker自动管理
    volumes:
      - adguard_work:/opt/adguardhome/work  # 命名卷adguard_work映射到容器工作目录：
                                            # 存储过滤规则、查询日志、缓存等动态数据，数据持久化且独立于容器生命周期
      - adguard_conf:/opt/adguardhome/conf  # 命名卷adguard_conf映射到容器配置目录：
                                            # 存储核心配置文件（如AdGuardHome.yaml），确保配置不丢失
    ports:  # 端口映射（主机端口:容器端口），按需保留或删除
      - "53:53/tcp"     # 普通DNS服务（TCP协议）
      - "53:53/udp"     # 普通DNS服务（UDP协议，DNS主要使用UDP）
      - "67:67/udp"     # DHCP服务器端口（如需用AdGuard作为DHCP服务器则保留）
      - "68:68/udp"     # DHCP客户端端口（配合DHCP服务器使用）
      - "80:80/tcp"     # HTTP端口：用于Web管理界面访问、广告过滤的HTTP请求拦截
      - "443:443/tcp"   # HTTPS端口：用于加密管理界面访问、DNS-over-HTTPS（DoH）服务
      - "443:443/udp"   # 443端口UDP：支持DoH相关的UDP通信
      - "3000:3000/tcp" # 初始化配置端口：首次启动时通过此端口访问设置界面（配置完成后可关闭）
      - "853:853/tcp"   # DNS-over-TLS（DoT）服务端口（加密DNS协议）
      - "853:853/udp"   # DNS-over-QUIC（DoQ）服务端口（基于QUIC的加密DNS）
      - "5443:5443/tcp" # DNSCrypt服务端口（另一种加密DNS协议）
      - "5443:5443/udp" # DNSCrypt服务的UDP端口
      - "6060:6060/tcp" # 调试端口：用于性能分析（如Go语言pprof工具），非必要可删除

# 定义命名卷（Docker会自动在宿主机创建并管理这些卷的存储路径，通常在/var/lib/docker/volumes/）
volumes:
  adguard_work:  # 卷名称：对应容器内的工作目录，存储动态数据
  adguard_conf:  # 卷名称：对应容器内的配置目录，存储核心配置

启动 AdGuard Home

启动容器
1
docker-compose up -d
查看容器状态
1
docker-compose ps

首次配置

1. 访问管理界面

本地访问: http://主机IP地址:3000
远程访问: http://<你的服务器IP>:3000

2. 初始设置步骤

选择语言（如中文），点击 Next。
阅读并接受服务条款，点击 Next。
设置管理员账户的用户名和密码。
完成配置后登录管理后台。

关键配置说明

1. 广告拦截规则

默认规则：系统已预装基础广告过滤规则。
自定义规则:
- 进入 Filtering → Rulesets → Manual，输入规则链接（例如 https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt）。

2. 家长控制

内容过滤:
- 在 Parent Control → Content Blocking 中勾选需要屏蔽的类别（如成人内容、赌博）。
屏幕时间管理:
- 在 Screen Time 中设置设备可用时间段（例如每天 18:00-22:00）。

3. 网络监控

查看实时流量：进入 Network → Dashboard 查看各设备的连接状态和 DNS 请求统计。

更新和卸载

### 更新
# 1. 停止 AdGuard Home 服务 
sudo systemctl stop AdGuardHome
# 2. 重新运行自动安装脚本(curl,wget,fetch)
# 3. 重启服务
sudo systemctl start AdGuardHome
# 4. 验证版本
/opt/AdGuardHome/AdGuardHome --version

### 卸载
# 1. 停止并禁用服务
sudo systemctl stop AdGuardHome
sudo systemctl disable AdGuardHome
# 2. 执行卸载命令
sudo /opt/AdGuardHome/AdGuardHome -s uninstall
# 3. 清理残留文件
sudo rm -rf /opt/AdGuardHome

### 更新
# 1. 从 Docker Hub 中拉出新版本
docker pull adguard/adguardhome 
# 2. 停止当前运行的容器
docker stop adguardhome 
# 3. 移除当前运行的容器
docker rm adguardhome 
# 4. 再次创建并运行容器，如果之前自定义过端口或挂载目录，重新创建时务必保持参数一致，否则可能导致配置或数据丢失

### 卸载
# 1. 停止当前运行的容器
docker stop adguardhome 
# 2. 移除当前运行的容器
docker rm adguardhome

### 更新
# 1. 拉取最新镜像
docker-compose pull 
# 2. 重新部署容器
docker-compose up -d 

### 卸载
# 进入存放adguard home的docker compose文件夹
# 基础删除（保留数据卷，仅删除容器和网络）
docker-compose down 
#彻底删除（包括数据卷，数据会丢失）
docker-compose down -v 
#额外清理（删除未使用的镜像）
docker-compose down --rmi all