Pi-hole 安装教程：先用单台设备验证过滤与恢复

Pi-hole 安装教程：先用单台设备验证过滤与恢复

Marcus Reid
2026年10月11日· 8 分钟阅读

Pi-hole 安装应从一台客户端开始，先证明过滤有效，再证明原 DNS 能恢复。把服务装在专用局域网主机上，只让测试电脑使用它；确认阻断和恢复都符合预期后，再考虑扩大范围。

关键要点：

  • 保留路由器原有 DNS 分发与 DHCP 服务。
  • 管理密码保护后台，防火墙限定哪些设备能查询 DNS。
  • 分别检查查询到达、阻断、例外、绕行路径与恢复。
  • 停止 Pi-hole 主机前，先恢复客户端原 DNS。

Pi-hole 安装需要哪些前提？

本文限定 Ubuntu 24.04 LTS x64 全新原生安装，以及一台有管理授权的 Windows 11 局域网客户端。发行参考分别为 Core v6.4.3、FTL v6.7.1、Web v6.6，三个组件独立编号；继续前须核对官方安装器实际安装的稳定组合。本文按官方文档整理，未进行完整端到端实测。［1］［2］［3］

决定长期维护 DNS 前，先用自建服务的维护框架判断责任。Pi-hole 过滤域名查询，不能保证消除所有广告；DNS 广告过滤原理解释其覆盖边界。

准备 sudo 权限、本地控制台、固定局域网地址和原客户端 DNS 记录。受管电脑、共享生产主机或未获授权网络应停止操作。已有安装升级前，先通过 Settings → Teleporter → Export 导出设置，并备份兼容的主机环境；把数据库拷回旧版不等于受支持的降级恢复。［14］

步骤 1：记录原配置

Windows 打开“设置 → 网络和 Internet”，选择正在使用的以太网连接或 Wi-Fi 网络，记录 DNS 是自动还是手动、全部 IPv4/IPv6 DNS 地址及加密 DNS 设置。保留 IP 地址与网关的分配方式。浏览器“安全 DNS”另行记录，它可能不使用 Windows 解析器。［5］

Ubuntu 记录主机地址、局域网网卡、当前解析器和防火墙规则。在路由器原有 DHCP 中保留主机地址，或采用管理员批准且不与租约冲突的静态配置；不把 Pi-hole 改成 DHCP 服务器。若防火墙按 IP 识别测试客户端，也为它保留地址。［4］

保存 /etc/resolv.conf 及其符号链接目标、resolved 配置，并记录 /etc/systemd/resolved.conf.d/90-pi-hole-disable-stub-listener.conf 是否已经存在；已有文件须保留原内容。先记录正常工作的基线：

readlink -f /etc/resolv.conf
resolvectl status
getent hosts example.com

离线保存恢复单：原 DNS、Pi-hole 与客户端地址、管理路径、新增规则。查询日志会暴露域名和客户端身份，只在本地收集测试时段，不公开完整日志或备份。

步骤 2：限定 DNS 与管理访问

在 Ubuntu 安装前检查监听与规则：

sudo ss -lntup
sudo ufw status numbered

DNS 需要 TCP 和 UDP 53，管理通常使用 80/443，也可能选用备用端口。与无关服务冲突时停止。安装器会自行关闭 systemd-resolved 的 Stub Listener，服务本身继续运行；FTL 启动前，主机 DNS 可能中断。不要自行停用系统解析器。本文不配置 DHCP 或 NTP。［4］［15］

入站策略应默认拒绝，同时保留回环流量。启用或调整防火墙前，保留经批准的 SSH 规则和本地控制台救援路径。以下仅是在已审查 UFW 策略上新增单客户端、单管理员权限的示例，必须替换网卡及两个地址：

LAN_IF='enp1s0'
CLIENT_V4='192.168.1.25'
ADMIN_V4='192.168.1.10'
sudo ufw allow in on "$LAN_IF" from "$CLIENT_V4" to any port 53 proto udp
sudo ufw allow in on "$LAN_IF" from "$CLIENT_V4" to any port 53 proto tcp
sudo ufw allow in on "$LAN_IF" from "$ADMIN_V4" to any port 443 proto tcp
sudo ufw status numbered

原有宽泛放行仍然有效，只删除你负责且与边界冲突的规则。UFW 未启用或尚无入站拒绝策略时，先由主机管理员建立策略，再接入客户端。放行实际 HTTPS 端口，保持 HTTP 管理入口关闭。［6］

IPv6 应有同等限制；本轮仅试 IPv4 时，IPv6 DNS 访问继续拒绝。无需路由器端口转发、公开 DNS 或访客网访问。Pi-hole 的 Allow only local requests 允许本地子网，不只允许选定设备；保留此模式，并用防火墙进一步收窄。不能为排障选择 Permit all origins。［7］

步骤 3：执行 Pi-hole 安装步骤

把官方安装器下载到主机，先阅读，再由主机操作者使用 sudo 执行：

wget -O basic-install.sh https://install.pi-hole.net
less basic-install.sh
sudo bash basic-install.sh
pihole version
pihole status
sudo pihole setpassword

选择预定局域网网卡及网络策略允许的上游 DNS，保持可选 DHCP 关闭。Pi-hole 服务身份由安装器管理，不改用个人管理员账户运行，也不随意改变文件归属绕过错误。交互式密码命令避免把密码写进命令参数。［8］［9］

核对安装版本与参考，差异须阅读发行说明，不混装旧组件。安装失败时不要更改 Windows DNS。若关闭 Stub Listener 后主机无法解析，使用本地控制台；只有确认该 drop-in 安装前不存在、现在仅含安装器的 [Resolve]／DNSStubListener=no 设置，才执行：

sudo systemctl stop pihole-FTL
sudo rm -- /etc/systemd/resolved.conf.d/90-pi-hole-disable-stub-listener.conf
sudo systemctl restart systemd-resolved
getent hosts example.com

逐行执行，任何命令报错都停止。文件原先存在或内容已被改动时，由管理员依据备份恢复。重试安装前核对 resolvectl status、原 /etc/resolv.conf 链接目标及主机正常解析。恢复失败时保留救援入口，不盲目覆盖解析配置。［15］［16］

首次 HTTPS 登录时，在获准 Windows 管理设备打开 Firefox about:profiles 页面，记下原默认配置文件，创建测试配置文件并在新浏览器中启动它。［18］Pi-hole 生成的证书最初不受浏览器信任；先在主机本地控制台记录 CA 指纹：

sudo openssl x509 -in /etc/pihole/tls_ca.crt -noout -fingerprint -sha256

仅通过已有可信管理路径复制 tls_ca.crt，不复制 tls.pem 或私钥。Firefox 打开“设置 → 隐私与安全 → 证书 → 查看证书 → 证书颁发机构 → 导入”，选择该 CA，与控制台记录比对指纹，一致后才允许网站信任。CA 信任覆盖它签发的全部证书，因此仅在此次测试配置文件中使用。［17］

访问名称必须匹配证书及 /etc/pihole/pihole.toml 的 webserver.domain。管理设备 DNS 无法解析该名称时，先记录原状态，再以管理员权限在 Windows C:\Windows\System32\drivers\etc\hosts 临时加入 LAN_IP hostname，替换两个值。用该名称和已放行 HTTPS 端口访问；名称或信任仍报警就停止，不绕过验证。登录后确认 DNS 监听模式、过滤已启用，并临时启用查询日志；登录成功不证明 DNS 访问受限。［10］［17］

步骤 4：只让 Windows 使用 Pi-hole

在当前连接的“DNS 服务器分配”中编辑为手动，首选 DNS 填 Pi-hole 局域网 IPv4 地址。IP 分配保持原样，不填公共备用 DNS，以免产生绕行。Pi-hole 的 53 端口提供普通 DNS，不给此地址套用 DoH 模板；这种逐设备设置保留路由器 DNS 不变。［5］［11］［13］

单独核对 IPv6 DNS。若另一解析器仍活跃，只能称为 IPv4 检查，不能宣称整台设备过滤。要验证双栈，先准备稳定 Pi-hole IPv6 地址，仅放行指定客户端 IPv6 来源，再设置对应解析器；无法辨认全部解析路径时停止。

浏览器安全 DNS 绕开系统时，仅在获授权的测试配置中暂时关闭并记录；VPN、代理和组织策略保持不变。如果 Windows 原先就不能解析，先按设备排障顺序检查；主机自身解析失败转Ubuntu DNS 故障定位。

步骤 5：验证阻断与单项例外

管理设备打开 Pi-hole 查询日志。Windows 对 example.com 发起新查询，先显式指定 Pi-hole，再用默认解析器；示例中的主机地址须替换：

nslookup example.com 192.168.1.53
nslookup example.com

核对日志时间、客户端、域名及允许状态。随后在 Domains 添加 example.com 的 exact deny 精确拒绝项并标注测试用途，不用通配或正则。重复两次查询，核对阻断状态，不以某个固定返回地址判定成功，因为阻断模式可能不同。［9］

再给同一域名添加 exact allow 精确允许项，演示单项例外；精确允许优先于精确拒绝。两条规则须适用于测试客户端的组，新安装通常为默认组。查询应恢复允许；只删临时允许项后应重新阻断，最后删临时拒绝项并确认正常解析。清理不能删除原有规则。［12］

这验证 DNS 决策，不验证网页外观。缓存页面、同域广告和浏览器独立解析都可能留下广告。若目标是改变公网出口而非过滤域名，可比较DNS 类工具与全流量隧道；安装 Pi-hole 不会提供该功能。

步骤 6：扩大范围前检查边界

下表是读者验收方法，不是作者实测结果。非授权来源检查需要第二台你控制的设备；没有就记录未执行，不能声称边界已实测。

检查方法预期现象失败时处理
显式与默认解析器的新查询Pi-hole 记录对应客户端和域名检查地址、网卡、端口规则及其它解析器
正常域名与精确拒绝域名正常允许，测试项记录阻断检查规则启用、客户端组和上游解析
添加后删除精确允许项加例外允许，删后重新阻断检查优先级与客户端组
核对 IPv4、IPv6、浏览器 DNS声称覆盖的每条路径均经 Pi-hole收窄结论或补齐缺失路径
未列入名单的自有设备发查询UDP、TCP DNS 都不提供服务先修正宽泛防火墙放行
未列入名单设备访问管理界面后台不可访问收窄实际 Web 端口，包含 IPv6
恢复客户端原 DNS默认新查询独立于 Pi-hole 正常工作复核原 DNS 模式与地址

超时不能单独证明防火墙拒绝；要在 Pi-hole 正常运行时比较两个来源。TCP 单独测试，可在 Windows nslookup 交互模式输入 set vc。不需要外部扫描。

如果单设备试用已经不够、还需要按域名使用不同的上游解析器，下一步可以看按域名分流上游的 AdGuard Home。

步骤 7：完成 Pi-hole DNS 恢复

Windows 精确恢复保存的状态：原来自动就恢复自动，原来手动就恢复完整服务器列表与加密 DNS 设置，同时恢复浏览器设置。停止 Pi-hole 前，先确认默认新查询和原先正常的页面可用。Microsoft 的 DNS 重置会恢复 DHCP 提供的服务器，不能代替恢复原手动列表。［11］

核对当前身份后，只删本轮临时域名项和防火墙新增项，恢复原日志设置。退役专用安装时，先确保客户端不再依赖，再用官方卸载器。备份保持私有，恢复确认前保留主机救援路径。［9］

在 Firefox 证书颁发机构中，仅移除匹配已记录指纹的 CA，恢复原默认配置文件，并只还原此次临时 hosts 项。官方卸载器会移除上述 resolved drop-in，完成后仍须核对主机 DNS；安装未完成时改用步骤 3 的条件化恢复。［16］［17］［18］

总结

  • 在受支持专用主机安装，只改一台客户端 DNS。
  • 管理认证、DNS 访问和过滤分别验收。
  • IPv6 与浏览器 DNS 是需要独立验证的路径。
  • 先恢复 DNS，再清理本轮配置。

常见问题

不改路由器 DNS 能安装 Pi-hole 吗？

可以。把一台获授权客户端的 DNS 直接设为 Pi-hole 局域网地址，路由器的 DNS 分发和 DHCP 服务保持原样。

必须使用树莓派吗？

不必。本文使用受支持的 Ubuntu x64 主机，所述原生安装方法不以树莓派硬件为前提。

能登录后台却不能解析是什么原因？

后台与 DNS 使用不同端口和访问控制。应检查 DNS 服务及 53 端口的两种协议，而不是削弱后台认证。

阻断已经有效，为什么仍有广告？

DNS 过滤针对匹配域名，无法消除允许域名内部的全部广告；浏览器独立 DNS 与缓存也会影响画面。

应该加公共 DNS 作为备用吗？

本轮受控过滤不加。备用解析器会形成绕行路径，需要恢复时应还原原 DNS 配置，而非增加另一出口。

IPv4 正常就可以忽略 IPv6 吗？

可以只做 IPv4 试验，但必须说明范围；其它 IPv6 DNS 仍可能独立解析，不属于已证明的过滤覆盖。

撤销客户端设置必须卸载 Pi-hole 吗？

不必。先恢复客户端原 DNS 并确认解析正常；所有依赖解除后，是否卸载属于单独的主机管理决定。

免责声明：这些步骤依据文档编写，不代表已完成设备实测。只操作获授权设备，并保留可用恢复路径。

来源:

  1. Pi-hole Core v6.4.3 — https://github.com/pi-hole/pi-hole/releases/tag/v6.4.3
  2. Pi-hole FTL v6.7.1 — https://github.com/pi-hole/FTL/releases/tag/v6.7.1
  3. Pi-hole Web v6.6 — https://github.com/pi-hole/web/releases/tag/v6.6
  4. Pi-hole Prerequisites — https://docs.pi-hole.net/main/prerequisites/
  5. Microsoft Essential Network Settings and Tasks in Windows — https://support.microsoft.com/en-us/windows/experience/connectivity-networking/essential-network-settings-and-tasks-in-windows
  6. Ubuntu Firewall — https://ubuntu.com/server/docs/how-to/security/firewalls/
  7. Pi-hole Interface Binding Behavior — https://docs.pi-hole.net/ftldns/interfaces/
  8. Pi-hole Installation — https://docs.pi-hole.net/main/basic-install/
  9. The pihole Command — https://docs.pi-hole.net/main/pihole-command/
  10. Pi-hole Configuration — https://docs.pi-hole.net/ftldns/configfile/
  11. Microsoft Set-DnsClientServerAddress — https://learn.microsoft.com/en-us/powershell/module/dnsclient/set-dnsclientserveraddress
  12. Pi-hole Domain Database — https://docs.pi-hole.net/database/domain-database/
  13. Pi-hole Post-Install — https://docs.pi-hole.net/main/post-install/
  14. Pi-hole Web v6.6 Teleporter — https://github.com/pi-hole/web/blob/v6.6/settings-teleporter.lp
  15. Pi-hole Core v6.4.3 Installer — https://github.com/pi-hole/pi-hole/blob/v6.4.3/automated%20install/basic-install.sh
  16. Pi-hole Core v6.4.3 Uninstaller — https://github.com/pi-hole/pi-hole/blob/v6.4.3/automated%20install/uninstall.sh
  17. Pi-hole TLS/SSL — https://docs.pi-hole.net/api/tls/
  18. Firefox Profile Manager — https://support.mozilla.org/en-US/kb/profile-manager-create-remove-switch-firefox-profiles

Sources checked 2026 年 10 月 11 日。

延伸阅读：

开启 3 天免费试用

注册即可免费体验全部高级功能。

*仅限新用户；每位用户只能获得一次试用。

免费试用

相关文章

Pi-hole 安装教程：先用单台设备验证过滤与恢复 | AethoVPN