AdguardHome Docker 容器化部署指南

概述

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

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

环境准备

Docker环境安装

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

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

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

docker --version
docker info

镜像准备

拉取ADGUARDHOME镜像

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

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

如需指定其他版本，可访问ADGUARDHOME镜像标签列表查看可用标签，并替换命令中的latest标签。

容器部署

准备数据持久化目录

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

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

启动ADGUARDHOME容器

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

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端口映射。

功能测试

容器状态检查

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

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

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

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

管理界面访问测试

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

http://服务器IP:3000

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

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

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

DNS服务功能测试

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

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

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

生产环境建议

数据安全与备份

ADGUARDHOME的配置和运行数据存储在挂载的主机目录中，建议：

• 定期备份/data/adguardhome目录，防止数据丢失
• 对备份文件进行加密存储，保护隐私数据

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

资源限制配置

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

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端口。

解决方法：

# 创建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服务器连通性

   # 进入容器
   docker exec -it adguardhome /bin/sh
   # 测试DNS解析
   nslookup example.com 8.8.8.8  # 使用Google DNS测试
   

3. 查看ADGUARDHOME日志，分析解析失败原因：docker logs adguardhome

参考资源

• ADGUARDHOME镜像文档（轩辕）
• ADGUARDHOME镜像标签列表
• ADGUARDHOME官方GitHub仓库
• Docker官方文档

总结

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

关键要点：

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

后续建议：

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

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