## 概述

ADGUARDHOME是一款网络级广告和跟踪器拦截DNS服务器，作为一款开源的隐私保护工具，它能够在网络层面为所有设备提供广告过滤和隐私保护功能，无需在每个设备上单独安装客户端软件。通过Docker容器化部署ADGUARDHOME，可以实现快速部署、环境隔离和版本管理，适用于家庭网络、小型企业网络等多种场景。

本文档将详细介绍ADGUARDHOME的Docker容器化部署流程，包括环境准备、镜像拉取、容器部署、功能测试及生产环境优化建议，旨在为用户提供一套可靠、可复现的部署方案。


## 环境准备

### Docker环境安装

ADGUARDHOME基于Docker容器运行，首先需要在目标服务器上安装Docker环境。推荐使用以下一键安装脚本，该脚本会自动配置Docker环境并优化相关参数：

```bash
bash <(wget -qO- https://xuanyuan.cloud/docker.sh)
```

安装完成后，可通过以下命令验证Docker是否正常运行：

```bash
docker --version
docker info
```


## 镜像准备

### 拉取ADGUARDHOME镜像

使用以下命令通过轩辕镜像加速地址拉取最新版本的ADGUARDHOME镜像：

```bash
docker pull xxx.xuanyuan.run/adguard/adguardhome:latest
```

如需指定其他版本，可访问 ADGUARDHOME镜像标签列表 `https://xuanyuan.cloud/r/adguard/adguardhome/tags` 查看可用标签，并替换命令中的`latest`标签。


## 容器部署

### 准备数据持久化目录

ADGUARDHOME需要持久化存储配置文件和运行数据，建议在主机上创建专用目录：

```bash
# 创建配置文件目录
mkdir -p /data/adguardhome/conf
# 创建数据存储目录
mkdir -p /data/adguardhome/work
# 设置目录权限
chmod -R 755 /data/adguardhome
```

### 启动ADGUARDHOME容器

使用以下命令启动ADGUARDHOME容器，根据实际需求调整端口映射和参数：

```bash
docker run -d \
  --name adguardhome \
  --restart unless-stopped \
  -v /data/adguardhome/conf:/opt/adguardhome/conf \
  -v /data/adguardhome/work:/opt/adguardhome/work \
  -p 53:53/tcp -p 53:53/udp \  # DNS服务端口
  -p 3000:3000/tcp \            # 初始配置界面端口
  -p 80:80/tcp \                # HTTP服务端口（用于DNS-over-HTTPS等）
  -p 443:443/tcp -p 443:443/udp \  # HTTPS服务端口
  adguard/adguardhome:latest
```

**参数说明**：
- `-d`：后台运行容器
- `--name adguardhome`：指定容器名称为adguardhome
- `--restart unless-stopped`：容器退出时自动重启（除非手动停止）
- `-v`：挂载主机目录到容器内，实现数据持久化
- `-p`：端口映射，根据ADGUARDHOME功能需求开放相应端口

> 注意：如需使用DHCP服务器功能，可能需要添加`--network host`参数使用主机网络（仅Linux系统支持），此时无需单独指定`-p`端口映射。


## 功能测试

### 容器状态检查

部署完成后，首先检查容器是否正常运行：

```bash
# 查看容器运行状态
docker ps | grep adguardhome

# 若容器未运行，查看错误日志
docker logs adguardhome
```

正常运行时，输出应显示容器状态为`Up`。

### 管理界面访问测试

ADGUARDHOME首次启动时，通过3000端口提供初始配置界面。在浏览器中访问：

```
http://服务器IP:3000
```

若无法访问，检查服务器防火墙规则是否允许3000端口入站，或通过以下命令测试端口连通性：

```bash
# 从服务器本地测试
curl http://127.0.0.1:3000

# 从客户端测试（替换为实际服务器IP）
curl http://服务器IP:3000
```

### DNS服务功能测试

ADGUARDHOME核心功能为DNS服务，可通过`nslookup`或`dig`命令测试DNS解析是否正常：

```bash
# 使用ADGUARDHOME作为DNS服务器解析域名
nslookup example.com 服务器IP
```

若解析成功，说明DNS服务基本功能正常。


## 生产环境建议

### 数据安全与备份

ADGUARDHOME的配置和运行数据存储在挂载的主机目录中，建议：
- 定期备份`/data/adguardhome`目录，防止数据丢失
- 对备份文件进行加密存储，保护隐私数据

```bash
# 示例：创建数据备份
tar -czf adguardhome_backup_$(date +%Y%m%d).tar.gz /data/adguardhome
```

### 资源限制配置

为避免容器过度占用主机资源，建议通过`--memory`和`--cpus`参数限制资源使用：

```bash
docker run -d \
  --name adguardhome \
  --restart unless-stopped \
  --memory=1G \  # 限制最大内存使用为1GB
  --cpus=0.5 \   # 限制CPU使用为0.5核
  -v /data/adguardhome/conf:/opt/adguardhome/conf \
  -v /data/adguardhome/work:/opt/adguardhome/work \
  -p 53:53/tcp -p 53:53/udp \
  -p 3000:3000/tcp \
  adguard/adguardhome:latest
```

根据实际网络规模和设备数量，调整资源限制参数。

### 网络优化

- **端口冲突处理**：ADGUARDHOME使用的53端口可能与系统自带DNS服务（如systemd-resolved）冲突，解决方法参考[故障排查](#故障排查)章节。
- **网络模式选择**：常规场景使用桥接网络（默认），需使用DHCP功能时切换至主机网络（`--network host`）。
- **防火墙配置**：仅开放必要端口，限制访问来源IP，增强安全性。


## 故障排查

### 常见问题及解决方法

#### 1. 53端口冲突（systemd-resolved服务）

**症状**：容器启动失败，日志显示`bind: address already in use`（绑定端口已被占用）。

**原因**：Linux系统默认的systemd-resolved服务占用53端口。

**解决方法**：
```bash
# 创建resolved配置文件
sudo mkdir -p /etc/systemd/resolved.conf.d/
sudo tee /etc/systemd/resolved.conf.d/adguardhome.conf <<EOF
[Resolve]
DNS=127.0.0.1
DNSStubListener=no
EOF

# 备份并重新链接resolv.conf
sudo mv /etc/resolv.conf /etc/resolv.conf.backup
sudo ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf

# 重启resolved服务
sudo systemctl reload-or-restart systemd-resolved
```

#### 2. 管理界面无法访问

**排查步骤**：
1. 检查容器是否运行：`docker ps | grep adguardhome`
2. 检查端口映射是否正确：`docker inspect adguardhome | grep PortBindings`
3. 检查主机防火墙规则：`sudo ufw status`（UFW防火墙）或查看`iptables`规则
4. 查看容器日志定位错误：`docker logs adguardhome`

#### 3. DNS解析异常

**排查步骤**：
1. 确认ADGUARDHOME上游DNS配置正确（通过管理界面检查）
2. 检查网络连通性：容器内测试上游DNS服务器连通性
   ```bash
   # 进入容器
   docker exec -it adguardhome /bin/sh
   # 测试DNS解析
   nslookup example.com 8.8.8.8  # 使用Google DNS测试
   ```
3. 查看ADGUARDHOME日志，分析解析失败原因：`docker logs adguardhome`


## 参考资源

-  ADGUARDHOME镜像文档（轩辕） `https://xuanyuan.cloud/r/adguard/adguardhome`
-  ADGUARDHOME镜像标签列表 `https://xuanyuan.cloud/r/adguard/adguardhome/tags`
-  ADGUARDHOME官方GitHub仓库 `https://github.com/AdguardTeam/AdGuardHome`
-  Docker官方文档 `https://docs.docker.com`


## 总结

本文详细介绍了ADGUARDHOME的Docker容器化部署方案，从环境准备、镜像拉取、容器部署到功能测试，提供了一套完整的实施流程。通过容器化部署，用户可以快速搭建网络级广告拦截DNS服务，同时确保部署过程的可重复性和环境隔离性。

**关键要点**：
- 使用轩辕镜像加速可提升ADGUARDHOME镜像拉取速度
- 数据持久化通过挂载主机目录实现，需注意备份重要配置
- 53端口可能与系统服务冲突，需提前排查并处理
- 管理界面初始访问端口为3000，完成配置后可调整

**后续建议**：
- 登录ADGUARDHOME管理界面完成初始配置，包括上游DNS设置、过滤规则添加等
- 根据网络规模和设备数量，优化ADGUARDHOME性能参数（如缓存大小、并发连接数）
- 深入学习ADGUARDHOME高级特性，如DNS-over-HTTPS、DNS-over-TLS等加密DNS功能
- 定期更新镜像版本，获取安全补丁和功能改进：`docker pull adguard/adguardhome:latest`并重启容器

通过合理配置和维护，ADGUARDHOME可有效提升网络隐私保护水平，为家庭或企业网络提供可靠的广告和跟踪器拦截服务。

ADGUARDHOME是一款网络级广告和跟踪器拦截DNS服务器，作为一款开源的隐私保护工具，它能够在网络层面为所有设备提供广告过滤和隐私保护功能，无需在每个设备上单独安装客户端软件。通过Docker容器化部署ADGUARDHOME，可以实现快速部署、环境隔离和版本管理，适用于家庭网络、小型企业网络等多种场景。

AdguardHome Docker 容器化部署指南

运维

编程语言

前端

AdGuardHome是一款开源DNS服务器，通过Docker容器化部署可实现网络级广告拦截和隐私保护。本文提供详细部署指南，包括环境准备、镜像拉取、容器配置、功能测试及生产优化建议，帮助用户快速搭建高效广告过滤系统，适用于家庭和小型企业网络环境。

数据备份

数据安全

安全补丁

数据存储

数据丢失

防火墙

服务器

容器

Docker

GitHub

Linux

DHCP

AI驱动 智领未来

4核4G3M云服务器 新用户低至38元/年！

对象存储COS新用户低至1元！


dsgc

热销域名限时优惠，新客首年免费！


domain

文章

问答

视频

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

AdguardHome Docker 容器化部署指南-腾讯云开发者社区-腾讯云

AdguardHome Docker 容器化部署指南

AdguardHome Docker 容器化部署指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐