AdguardHome Docker 容器化部署指南

830次阅读

共计 3834 个字符，预计需要花费 10 分钟才能阅读完成。

概述

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. 管理界面无法访问

排查步骤：

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

3. DNS 解析异常

排查步骤：

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