Docker部署Pi-Hole：局域网广告过滤与DNS服务器搭建指南

还在为网页和应用里层出不穷的广告烦恼吗？无论是消耗系统资源还是暗藏安全风险，广告都令人不胜其扰。虽然为每台电脑的浏览器安装插件是一种方法，但如果你希望一劳永逸地保护整个家庭网络里的所有设备，那么部署一个网络层面的广告过滤方案会是更聪明的选择。这正是 Pi-Hole 这类工具的用武之地。

Pi-Hole 是一个功能强大的开源项目，它本质上是一个网络广告拦截器，通过充当本地 DNS 服务器来工作。当你的所有设备将 DNS 请求指向 Pi-Hole 时，它会拦截并屏蔽已知的广告与追踪域名，从而为你的整个局域网提供保护。这不仅提升了浏览速度，还能有效过滤应用程序内的广告。更棒的是，你可以通过一个简洁的网页界面来监控和管理一切。

本文译自：How to deploy Pi-Hole with Docker and stop ads on every device on your LAN
作者：Jack Wallen

在开始之前，有一个重要的前提需要了解：要让 Pi-Hole 发挥最大功效，最理想的方式是将你的路由器 DNS 设置指向 Pi-Hole 服务器。但是，并非所有互联网服务提供商（ISP）都允许用户修改路由器 DNS。例如，部分 AT&T Fiber 用户可能会遇到此限制。请先确认你的网络环境是否支持此操作。

接下来，我们将使用 Docker 来快速部署 Pi-Hole，这是一项在 云栈社区 备受开发者推崇的容器化技术。这种方法能让我们轻松管理应用及其依赖，避免环境配置的繁琐。

安装 Docker

由于我们将 Pi-Hole 部署为 Docker 容器，因此需要先安装 Docker 环境。macOS 或 Windows 用户可以直接安装 Docker Desktop。如果你使用的是 Linux 系统（如 Ubuntu Server 24.04），则可以按照以下步骤操作。

首先，更新包索引并安装必要工具，然后添加 Docker 的官方 GPG 密钥：

sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

接着，添加 Docker 的官方软件源：

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

现在，更新包列表并安装 Docker 及其相关组件：

sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin git -y

为了无需 sudo 即可运行 Docker 命令（请注意，这方便但也带来一定的安全考虑），需要将当前用户添加到 docker 组：

sudo usermod -aG docker $USER

执行此命令后，请注销并重新登录系统，以使组权限生效。之后，你可以通过以下命令验证 Docker 是否安装成功：

docker ps -a

如果看到一个空的容器列表且无错误信息，说明 Docker 已就绪。

部署 Pi-Hole

Docker 准备完毕后，我们就可以启动 Pi-Hole 容器了。在运行下面的命令前，有两点需要注意：

1. 端口映射：确保命令中 -p 参数左侧（宿主机端口）未被占用，你可以根据实际情况调整。
2. 管理员密码：务必将 PASSWORD 替换为一个强密码，这是访问 Pi-Hole 管理界面的凭证。

综合考虑网络配置与管理需求，完整的部署命令如下：

docker run --name pihole \
  -p 54:53/tcp -p 54:53/udp \
  -p 8081:80/tcp \
  -p 443:443/tcp \
  -e TZ=America/Kentucky/Louisville \
  -e FTLCONF_webserver_api_password="PASSWORD" \
  -e FTLCONF_dns_listeningMode=all \
  -v ./etc-pihole:/etc/pihole \
  -v ./etc-dnsmasq.d:/etc/dnsmasq.d \
  --cap-add NET_ADMIN \
  -d --restart unless-stopped \
  pihole/pihole:latest

执行命令后，请等待一两分钟让容器完全启动。你可以通过 docker ps -a 命令查看容器状态，当状态显示为 “healthy” 时，说明 Pi-Hole 已部署完成。

访问 Pi-Hole 管理界面

要管理你的广告过滤服务，需要访问 Pi-Hole 的网页控制台。在你的浏览器中访问 http://<服务器IP>:8081/admin/（将 <服务器IP> 替换为你运行 Docker 的主机 IP 地址）。

首次访问时，系统会要求你输入密码。请输入之前部署命令中为 FTLCONF_webserver_api_password 环境变量设置的那个“PASSWORD”。

登录成功后，你将看到 Pi-Hole 的仪表盘。

图 1：一个新部署的 Pi-Hole 实例已准备就绪。

配置网络设备使用 Pi-Hole

要让网络中的设备真正享受到广告过滤，你需要将它们指向 Pi-Hole。主要有两种方法：

1. 逐台设备配置：手动将每台电脑、手机等设备的 DNS 服务器地址设置为 Pi-Hole 所在主机的 IP 地址。这种方法灵活但繁琐。
2. 全局网络配置（推荐）：在路由器上修改 DNS 设置，让所有通过 DHCP 自动获取 IP 的设备都默认使用 Pi-Hole。这通常需要在路由器管理页面完成。修改后，你可能需要在路由器上关闭 DHCP 服务，并在 Pi-Hole 上启用其内置的 DHCP 服务器，以便更统一地管理网络。

要在 Pi-Hole 中启用 DHCP 服务器，请进入网页控制台的 Settings -> DHCP 页面。勾选启用 DHCP 服务器，设置要分发的 IP 地址范围，并填入你的主路由器（网关）的 IP 地址。

图 2：启用 Pi-Hole 的 DHCP 功能，可以更方便地管理网络地址分配。

完成此操作并保存应用后，你可以重启网络中的设备，或让它们续订 DHCP 租约。之后，这些设备将自动使用 Pi-Hole 提供的 DNS 服务，从而被屏蔽广告。

通过以上步骤，你就成功搭建了一个属于自己且覆盖全网的广告过滤系统。无论是网页浏览还是手机应用，恼人的广告都将大幅减少，这不仅是 网络/系统 层面的优化，也极大地提升了日常数字生活的整洁与效率。如果你在配置过程中遇到任何关于 DNS 或 DHCP 的问题，也欢迎在相关的 运维/DevOps/SRE 板块进行交流探讨。