用途
本技能是面向家庭实验室（homelab）的 Pi-hole DNS 操作指南。Pi-hole 是运行在树莓派或任意 Linux 主机上的网络级 DNS 广告拦截器。网络中每台设备都能自动获得广告与恶意域名拦截，无需安装浏览器扩展。
适用时机包括：在树莓派或 Linux 主机上安装 Pi-hole；将 Pi-hole 配置为家庭网络的 DNS 服务器；添加或管理屏蔽列表；设置 DNS-over-HTTPS（DoH）上游解析器；创建本地 DNS 记录（如 nas.home.lan、pi.home.lan）；排查安装 Pi-hole 后设备失去互联网访问的问题；让 Pi-hole 与 DHCP 并行运行或替代 DHCP。
工作原理
普通流程（无 Pi-hole）：设备请求 ads.tracker.com → ISP DNS → 返回真实 IP → 广告加载。
使用 Pi-hole：设备请求 ads.tracker.com → Pi-hole DNS → 拦截（返回 0.0.0.0）→ 无广告。所有 DNS 查询先经过 Pi-hole，Pi-hole 对照屏蔽列表检查，被拦截的域名返回空响应，广告/追踪器永不加载；被允许的域名转发到上游解析器（Cloudflare、Google 等）。
安装
Docker（推荐）
Docker 是安装 Pi-hole 最简单的方式，更新与备份也很直接。文档提供 docker-compose.yml 配置，包含端口映射（53/tcp、53/udp、80/tcp 用于 Web 管理）、环境变量（TZ、WEBPASSWORD、PIHOLE_DNS_、DNSMASQ_LISTENING）、卷挂载、restart 策略，以及仅在 Pi-hole 提供 DHCP 时需要的 NET_ADMIN 能力。部署前需将 <pinned-release-tag> 替换为当前 Pi-hole 发布标签；长期运行的 DNS 基础设施应避免使用 latest，以便升级可控可审查。密码应通过 .env 文件设置，chmod 设为 600 并排除在 git 之外，不要直接写入 compose 文件。Web 管理界面地址为 http://<pi-ip>/admin。
裸机安装（Raspberry Pi OS / Debian / Ubuntu）
Pi-hole 安装前需要静态 IP。文档给出在 Pi OS 上编辑 /etc/dhcpcd.conf 分配静态 IP 的示例，并建议先下载安装脚本、审查后再运行（curl 下载到 pi-hole-install.sh，使用 less 查看，再 bash 执行）。交互式安装步骤包括：选择网络接口（推荐有线 eth0）、选择上游 DNS、确认静态 IP、安装 Web 管理界面，并记录最后显示的管理员密码。
将网络指向 Pi-hole
方法一：在路由器 DHCP 设置中修改 DNS（推荐）。主 DNS 设为 Pi-hole IP；为严格拦截可将备用 DNS 留空，或使用第二个 Pi-hole；使用公共备用 DNS（如 1.1.1.1）可提高部署期间可用性，但由于客户端可能直接查询它，可能会绕过拦截。所有设备在下次 DHCP 续约时自动获得 Pi-hole 作为 DNS；强制续约可重连 Wi-Fi 或在 Linux 上运行 sudo dhclient -r && sudo dhclient。
方法二：按设备设置 DNS（适合全网部署前测试）。Windows 在控制面板 → 网络适配器 → IPv4 属性 → 手动设置 DNS；macOS 在系统设置 → 网络 → 详细信息 → DNS 手动设置；Linux 使用 /etc/resolv.conf 或 NetworkManager。
方法三：Pi-hole 作为 DHCP 服务器（替代路由器 DHCP）。在 Pi-hole 管理界面 → Settings → DHCP → 启用，但必须先禁用路由器 DHCP，否则同一网络上的两个 DHCP 服务器会冲突。优点是主机名解析自动生效（设备注册自己的名称）。
屏蔽列表管理
在 Pi-hole 管理界面 → Adlists → 添加新列表。文档推荐的列表包括 StevenBlack/hosts（默认，20 万+ 域名）、blocklistproject 的 malware 列表与 tracking 列表。添加列表后需在 Tools → Update Gravity 下载并编译所有屏蔽列表。若误拦截正常网站，可在白名单中添加域名（例如 api.my-legitimate-service.com）。可通过 Dashboard → Query Log 实时查看被拦截的查询。
DNS-over-HTTPS 上游
DNS-over-HTTPS 加密 DNS 查询，使 ISP 无法看到解析的站点。文档说明安装 cloudflared（Cloudflare 的 DoH 代理）：优先使用 Cloudflare 的软件包仓库以获得自动签名验证；若直接下载二进制文件，应固定发布版本并校验校验和。随后创建 /etc/cloudflared/config.yml 配置（proxy-dns、proxy-dns-port 5053、上游 https://1.1.1.1/dns-query 与 https://1.0.0.1/dns-query），通过 sudo cloudflared service install 创建 systemd 服务并启动、设为开机自启。最后在 Pi-hole 管理界面 → Settings → DNS → Custom upstream DNS 设为 127.0.0.1#5053，并取消勾选其他所有上游解析器。
本地 DNS 记录
让服务可通过名称访问（如 nas.home.lan、grafana.home.lan）。文档指出 .home.lan 在 homelab 中广泛使用且实践可行；IETF 为本地使用保留的后缀是 .home.arpa（RFC 8375），遵循标准可使用该后缀；Pi-hole DNS 记录应避免使用 .local，因为它与 mDNS/Bonjour 冲突。在 Pi-hole 管理界面 → Local DNS → DNS Records 添加域名与 IP 映射（如 nas.home.lan → 192.168.30.10、pi.home.lan → 192.168.30.2 等），任意设备即可通过 ping 或浏览器访问。子域名可添加 CNAME，例如 portainer.home.lan → pi.home.lan。
故障排查
常用命令包括：pihole -q example.com 检查域名是否被拦截及来自哪个列表；pihole -w example.com 立即加入白名单；pihole status 检查 pihole-FTL 是否运行；dig @192.168.3.2 google.com 直接向 Pi-hole 测试 DNS；pihole restartdns 重启 Pi-hole DNS；pihole -t 实时查看所有查询（或在 Web 管理界面的 Query Log 中按客户端筛选）；pihole -g 刷新屏蔽列表。
反模式与最佳实践
反模式：只依赖单个 Pi-hole 而无恢复路径（Pi 崩溃或断电时 DNS 可能停止）；未设置静态 IP 就安装 Pi-hole（Pi 获得新 DHCP IP 后所有设备失去 DNS）；未先禁用路由器 DHCP 就启用 Pi-hole DHCP（两个 DHCP 服务器分发冲突 IP）；从不更新 gravity（新广告与恶意域名会不断出现，过期列表会漏掉它们）。
最佳实践：安装 Pi-hole 前为 Pi 设置静态 IP 或 DHCP 保留；将 Pi-hole 用作主 DNS，若需冗余应添加第二个 Pi-hole 而非公共解析器（严格拦截场景）；使用 cloudflared 启用 DoH 加密上游查询；将 home.lan 设为本地域并为所有服务创建 DNS 记录；偶尔查看 Query Log，被拦截的查询可反映设备行为。
相关技能：homelab-network-setup、homelab-vlan-segmentation、homelab-wireguard-vpn。