NAS 与运维

Pi-hole:局域网 DNS 过滤入门

  • 0 次阅读
  • 0 条评论
文章摘要

Pi-hole 通过 DNS 规则阻断指定域名的解析,适合集中观察和管理局域网 DNS。是否生效取决于终端实际使用的解析服务。 系统提供集中 DNS 查询与过滤管理,客户端使用它解析域名后,规则才会生效。管理页面中的请求记录有助于识别误拦截和异常查询。 适合希望统一维护家庭 DNS 的环境。部署重点是标准 DNS 端口、固定地址和恢复路径,先试一台设备比直接改全网更容易排错。

项目介绍

Pi-hole 通过 DNS 规则阻断指定域名的解析,适合集中观察和管理局域网 DNS。是否生效取决于终端实际使用的解析服务。

系统提供集中 DNS 查询与过滤管理,客户端使用它解析域名后,规则才会生效。管理页面中的请求记录有助于识别误拦截和异常查询。

适合希望统一维护家庭 DNS 的环境。部署重点是标准 DNS 端口、固定地址和恢复路径,先试一台设备比直接改全网更容易排错。

核心功能

功能 作用与使用方式
域名过滤 按订阅与自定义规则阻断
查询观察 查看设备请求与响应
允许清单 恢复误拦的明确域名
上游设置 选择实际可用的解析服务
集中管理 减少逐台设备维护规则

功能示意

Pi-hole 功能示意图

图 1:自制功能示意图,概括本文的使用要点。

项目信息

项目 说明
类型 Docker
分类 NAS 与运维
项目仓库 pi-hole/pi-hole
官方入口或文档 直接访问
整理日期 2026-11-14

安装或使用条件

准备支持 Docker Compose 的主机、空闲端口与持久化目录。群晖可使用 Container Manager 的项目功能;示例目录以 /volume1/docker 为基准,其他存储卷需要自行替换。

安装与使用步骤

  1. 创建持久化目录,检查 NAS 是否已有 DNS 服务占用 TCP/UDP 53。端口冲突时先设计独立地址或主机,不把标准 DNS 服务随意改成客户端不会使用的端口。
  2. 启动后打开管理页面,确认上游 DNS,再在一台测试电脑上把 DNS 指向 NAS 地址。先不修改整个路由器的 DHCP DNS。
  3. 检查查询日志与拦截结果,测试常用站点和设备;确认稳定后再决定是否向其他客户端分配。
  4. 遇到页面异常时先暂时停用对应规则或为明确域名添加例外,观察日志,避免一次增加大量未知订阅。

首次使用与操作检查

在测试设备指定新 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。只回退镜像不一定能回退已经迁移过的数据库。

参考资料