AdGuardHome 端口冲突快速搞定：53 与 3000 默认端口一次改对

【免费下载链接】AdGuardHomeNetwork-wide ads & trackers blocking DNS server项目地址: https://gitcode.com/gh_mirrors/ad/AdGuardHome

刚部署 AdGuardHome 时最常见的报错就是address already in use——这是典型的 AdGuardHome 端口冲突。原因不复杂：它默认占用 53（DNS）和 3000（Web 管理界面）两个端口，而这两个端口恰好都是服务器上"热门货"。这篇指南带你按部署方式把端口改好、验证通过。

TL;DR：只关心答案看这里

📌 编辑AdGuardHome.yaml，把dns.port改成 1024 以上的空闲端口（如 5353），把http.address改成如0.0.0.0:8080，然后重启服务。就这两个字段。

为什么会撞端口

AdGuardHome 是"一个进程、两副面孔"：一侧是面向全家设备提供解析的 DNS 服务，默认听 53 端口——这正好是系统自带 dnsmasq、systemd-resolved 的本职端口，几乎必然打架；另一侧是 Web 管理界面，默认听 3000 端口——这个端口很多 Node 应用、其他代理管理页也爱用，撞车概率也不低。两者相互独立，所以常常只需改其中一个。

先确认谁占用了 53 端口

动手前先定位，别盲改。任选一条：

ss -tulnp | grep -E ':(53|3000)\b' lsof -iUDP:53 -iTCP:3000

输出里能看到是dnsmasq、systemd-resolved还是别的进程。确认"被谁占"之后，再决定是把对方停掉，还是给 AdGuardHome 让个新端口。

裸机 / 直接改配置文件怎么改

配置文件默认在二进制同目录（AdGuardHome.yaml），仓库里有一份可直接对照的示例 AdGuardHome.example.yaml。最小改动如下：

dns: port: 5353 http: address: 0.0.0.0:8080

改完执行systemctl restart AdGuardHome（或你实际的启动方式）。如果服务文件里写死了配置路径，改的必须是同一个文件——这是新手最容易改错的地方。

Docker 部署怎么同步改端口

Docker 场景多一层：容器内端口和宿主机映射要一起看。AdGuardHome 镜像支持环境变量覆盖，docker-compose.yml里这样写最省事：

environment: - DNS_PORT=5353 - WEB_ADDR=0.0.0.0:8080 ports: - "8080:8080" # 宿主机:容器 - "5353:5353/udp"

🐳 注意ports左边的宿主机端口要跟着改，漏改映射是 Docker 场景下"改了半天还是不通"的头号原因。

改完跑这几条命令验证

ss -tulnp | grep AdGuardHome # 应看到新端口在 LISTEN dig @127.0.0.1 -p 5353 example.com # 换你的新 DNS 端口 curl -I http://127.0.0.1:8080 # 管理界面应返回 HTTP 响应

三条都通，再登录http://<服务器IP>:8080看看面板和过滤列表是否正常加载（过滤流程可参考 agh-filtering.png 的示意）。

容易踩的坑

• 新端口在防火墙 / 安全组里没放行，容器内通、外面不通。
• 设备端 DNS 还指向旧端口（路由器 DHCP 下发地址也要改）。
• 选了 1024 以下的端口，非 root 进程直接绑不上；5353 这类高端口更稳。
• 只改了配置文件，忘了 Dockerports映射或 systemd 里--config指向的是别的文件。
• 想省事的可以改用命令行--config指向外部配置文件，避免升级时覆盖安装目录里的配置。

改完端口只是部署的第一关，想继续了解配置如何随版本演进，可以看 configmigrate 模块；项目整体行为与配置项说明见 README.md。

【免费下载链接】AdGuardHomeNetwork-wide ads & trackers blocking DNS server项目地址: https://gitcode.com/gh_mirrors/ad/AdGuardHome