Docker安装AdGuard后无法解析DNS？

Question

在使用Docker部署AdGuard Home后，部分用户遇到容器运行正常但无法解析DNS的问题。常见表现为客户端设置正确却无法上网或域名解析超时。此问题通常源于宿主机的53端口被占用（如systemd-resolved服务），导致AdGuard无法绑定默认DNS端口；或网络模式配置不当，如未使用host模式或端口映射缺失。此外，防火墙规则、SELinux策略或容器内配置未生效也可能是诱因。需检查日志输出、端口占用情况及配置文件权限，确保AdGuard真正监听在预期接口与端口上。

Answer 1

使用Docker部署AdGuard Home后DNS解析失败的深度排查与解决方案

1. 问题现象与初步诊断

在基于Docker部署AdGuard Home的环境中，部分用户反馈容器状态正常（docker ps显示运行中），但客户端配置了该DNS服务器后仍无法访问互联网或出现域名解析超时。典型表现为：

• Ping 域名提示“找不到主机”
• nslookup 或 dig 查询返回超时或无响应
• AdGuard Web界面可访问，但日志未记录任何查询请求

这表明AdGuard并未实际接收到来自客户端的DNS查询流量。

2. 根本原因分析框架

从网络栈、系统服务到容器配置，潜在故障点分布广泛。以下为常见诱因分类：

类别	具体原因	检测方式
端口冲突	systemd-resolved 占用53端口	netstat -tulnp | grep :53
网络模式	未使用host模式或端口映射缺失	docker inspect network_mode
防火墙	iptables/firewalld 阻断UDP/TCP 53	iptables -L -n
SELinux	策略限制容器绑定特权端口	getenforce && audit2why
配置加载	挂载目录权限错误导致配置未生效	ls -l /path/to/config

3. 深度排查流程图

graph TD
    A[客户端无法解析] --> B{容器是否监听53端口?}
    B -- 否 --> C[检查宿主机53端口占用]
    B -- 是 --> D{是否有DNS查询日志?}
    C --> E[停用systemd-resolved或修改其端口]
    D -- 否 --> F[检查网络模式和端口映射]
    D -- 是 --> G[检查上游DNS连通性]
    F --> H[使用host模式或正确-p映射]
    H --> I[验证防火墙规则放行53端口]
    I --> J[确认SELinux未阻止bind操作]
    J --> K[检查config目录读写权限]
    K --> L[重启容器并验证]
    

4. 关键技术点详解

4.1 systemd-resolved 占用53端口

现代Linux发行版默认启用systemd-resolved，其监听127.0.0.53:53，但会通过Stub Listener机制影响全局53端口可用性。

解决方法：

1. 临时停止服务：sudo systemctl stop systemd-resolved
2. 禁用开机启动：sudo systemctl disable systemd-resolved
3. 修改/etc/systemd/resolved.conf设置DNSStubListener=no
4. 重启服务：sudo systemctl reload-or-restart systemd-resolved

4.2 Docker网络模式选择

AdGuard Home需直接监听宿主机网络接口，推荐使用host网络模式以避免NAT和端口映射复杂性。

Docker Compose示例：

version: '3'
services:
  adguard:
    image: adguard/adguardhome
    network_mode: host
    volumes:
      - ./ag-data:/opt/adguardhome/work
      - ./ag-config:/opt/adguardhome/conf
    restart: always

4.3 防火墙与SELinux协同排查

即使端口开放，安全模块仍可能拦截绑定操作。

CentOS/RHEL系列需执行：

# 放行DNS端口
sudo firewall-cmd --add-port=53/tcp --permanent
sudo firewall-cmd --add-port=53/udp --permanent
sudo firewall-cmd --reload

# SELinux允许容器绑定网络端口
sudo setsebool -P container_connect_any 1

5. 日志驱动的问题定位

利用Docker日志快速判断AdGuard是否启动成功并监听端口：

docker logs <container_id> | grep -i listen

预期输出应包含：

Starting the DNS server on :53 [UDP/TCP]

若未见此类日志，则说明配置未生效或存在权限问题。

6. 配置文件挂载与权限校验

确保挂载的配置目录具有正确属主：

# 创建目录
mkdir -p ag-data ag-config

# 设置权限（AdGuard Home运行用户通常为uid=1000）
sudo chown -R 1000:1000 ag-data ag-config

否则容器内进程无法写入工作数据，导致配置回退至默认状态。

7. 终极验证步骤

完成所有修复后，按顺序执行验证：

1. ss -tulnp | grep :53 确认adguard进程监听
2. dig @<宿主机IP> google.com 测试解析能力
3. 查看AdGuard Web界面“统计”页是否有查询流入
4. 客户端刷新DNS缓存后测试上网功能