项目介绍
Pi-hole 通过 DNS 规则阻断指定域名的解析,适合集中观察和管理局域网 DNS。是否生效取决于终端实际使用的解析服务。
系统提供集中 DNS 查询与过滤管理,客户端使用它解析域名后,规则才会生效。管理页面中的请求记录有助于识别误拦截和异常查询。
适合希望统一维护家庭 DNS 的环境。部署重点是标准 DNS 端口、固定地址和恢复路径,先试一台设备比直接改全网更容易排错。
核心功能
| 功能 | 作用与使用方式 |
|---|---|
| 域名过滤 | 按订阅与自定义规则阻断 |
| 查询观察 | 查看设备请求与响应 |
| 允许清单 | 恢复误拦的明确域名 |
| 上游设置 | 选择实际可用的解析服务 |
| 集中管理 | 减少逐台设备维护规则 |
功能示意

图 1:自制功能示意图,概括本文的使用要点。
项目信息
| 项目 | 说明 |
|---|---|
| 类型 | Docker |
| 分类 | NAS 与运维 |
| 项目仓库 | pi-hole/pi-hole |
| 官方入口或文档 | 直接访问 |
| 整理日期 | 2026-11-14 |
安装或使用条件
准备支持 Docker Compose 的主机、空闲端口与持久化目录。群晖可使用 Container Manager 的项目功能;示例目录以 /volume1/docker 为基准,其他存储卷需要自行替换。
安装与使用步骤
- 创建持久化目录,检查 NAS 是否已有 DNS 服务占用 TCP/UDP 53。端口冲突时先设计独立地址或主机,不把标准 DNS 服务随意改成客户端不会使用的端口。
- 启动后打开管理页面,确认上游 DNS,再在一台测试电脑上把 DNS 指向 NAS 地址。先不修改整个路由器的 DHCP DNS。
- 检查查询日志与拦截结果,测试常用站点和设备;确认稳定后再决定是否向其他客户端分配。
- 遇到页面异常时先暂时停用对应规则或为明确域名添加例外,观察日志,避免一次增加大量未知订阅。
首次使用与操作检查
在测试设备指定新 DNS,访问几个常用服务并核对日志。新增一条测试规则,再移除它,确认缓存刷新后的表现。
没有日志时先查客户端实际 DNS 与加密解析设置。全网切换前保留原路由配置,避免 NAS 维护期间影响其他设备上网。
Docker Compose
采用官方 docker-pi-hole 当前 v6 配置项,仅提供 DNS 与 HTTP 管理页面,不启用 DHCP、NTP 和额外能力。先确认宿主 53 端口空闲,使用下方命令自动生成 PIHOLE_PASSWORD,管理页使用 http://NAS_IP:8089/admin。
群晖目录准备
在群晖 SSH 终端执行下面这一段,再将下方配置保存为 /volume1/docker/pihole/compose.yaml。也可在 Container Manager 中新建项目,选择该目录并粘贴配置。
sudo sh <<'HALO_PREPARE'
set -eu
mkdir -p /volume1/docker/pihole /volume1/docker/pihole/etc-pihole
cd /volume1/docker/pihole
umask 077
touch .env
if ! grep -q "^PIHOLE_PASSWORD=." .env; then
generated_secret=$(openssl rand -hex 32)
printf 'PIHOLE_PASSWORD=%s\n' "$generated_secret" >> .env
fi
chmod 600 .env
HALO_PREPARE
cd /volume1/docker/pihole
所需密码和密钥已自动生成到项目目录的 .env,已有非空值会保留。查看初始化密码可在自己的终端执行 sudo cat /volume1/docker/pihole/.env;该文件只保留在本机。
services:
pihole:
image: pihole/pihole:latest
restart: unless-stopped
ports:
- "53:53/tcp"
- "53:53/udp"
- "8089:80/tcp"
environment:
TZ: Asia/Shanghai
FTLCONF_webserver_api_password: "${PIHOLE_PASSWORD}"
FTLCONF_dns_listeningMode: ALL
volumes:
- /volume1/docker/pihole/etc-pihole:/etc/pihole
在项目目录保存为 compose.yaml 后,先检查配置,再启动:
docker compose config --quiet
docker compose up -d
docker compose ps
docker compose logs --tail=100
配置与常见问题
- v6 使用 FTLCONF_* 变量,不能直接沿用旧版 WEBPASSWORD 等配置。
- 此方案不接管 DHCP,不需要 NET_ADMIN、SYS_TIME 或特权模式。
- 不要让公网设备任意递归查询自己的 DNS 服务,限制 53 端口到可信网络。
- 页面无法打开:先用
docker compose ps检查状态,再核对宿主机端口、NAS 防火墙与应用日志。不要把容器端口随意改成另一个数字。 - 文件无法保存:核对宿主目录是否存在、挂载方向及运行用户的读写权限。不要直接给整个存储卷开放所有权限。
更新与备份
保存规则、白名单、配置导出和路由器原设置。
更新前保留原配置和数据备份,阅读所用版本的升级说明;确认兼容后再执行 docker compose pull 和 docker compose up -d。只回退镜像不一定能回退已经迁移过的数据库。