homelab-pihole-dns

Homelab Pi-hole DNS

Pi-hole 是一款运行在树莓派（Raspberry Pi）或任意 Linux 主机上的全网 DNS 广告拦截器。它能在网络层自动为局域网内的所有设备拦截广告与恶意域名，完全无需在浏览器安装扩展插件。

适用场景

• 在树莓派或 Linux 主机上安装 Pi-hole
• 将 Pi-hole 配置为家庭局域网的 DNS 服务器
• 添加或管理域名黑名单（Blocklists）
• 配置 DNS-over-HTTPS (DoH) 上游解析器
• 创建本地 DNS 记录（例如 nas.home.lan、pi.home.lan）
• 排查安装 Pi-hole 后部分设备无法上网（DNS 解析失效）的问题
• 将 Pi-hole 与现有 DHCP 配合使用，或直接接管 DHCP 服务

Pi-hole 工作原理

常规流程（未安装 Pi-hole）：
  设备 → 请求 ads.tracker.com → 运营商 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
services:
  pihole:
    image: pihole/pihole:<pinned-release-tag>
    container_name: pihole
    ports:
      - "53:53/tcp"
      - "53:53/udp"
      - "80:80/tcp"          # Web 管理后台
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # 通过 .env 文件或 secret 传入
      PIHOLE_DNS_: "1.1.1.1;1.0.0.1"
      DNSMASQ_LISTENING: "all"
    volumes:
      - "./etc-pihole:/etc/pihole"
      - "./etc-dnsmasq.d:/etc/dnsmasq.d"
    restart: unless-stopped
    cap_add:
      - NET_ADMIN              # 仅在开启 Pi-hole DHCP 服务时需要

部署前请将 <pinned-release-tag> 替换为 Pi-hole 当前的具体 Release 标签。
作为长期运行的 DNS 基础设施，切忌直接使用 latest 镜像，以便升级按需且可追溯。

请在 docker-compose.yml 同级目录下新建 .env 文件来配置 PIHOLE_WEBPASSWORD，使用 chmod 600 限制权限，并将其排除在 Git 版本控制之外 —— 不要把密码硬编码在 Compose 文件中。

Web 管理后台访问地址：http://<pi-ip>/admin

原生裸机安装（Raspberry Pi OS / Debian / Ubuntu）

安装 Pi-hole 之前，必须先为服务器配置静态 IP。

# 步骤 1：分配静态 IP（以 Pi OS 的 /etc/dhcpcd.conf 为例）
sudo nano /etc/dhcpcd.conf
# 在文件末尾添加以下内容：
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# 步骤 2：先下载并检查安装脚本再执行。
# 建议优先参考 Pi-hole 针对你当前 OS/版本的官方文档包路径或安装流程。
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh   # 仔细审查脚本内容

# 步骤 3：运行安装脚本
bash pi-hole-install.sh

# 按照交互式安装向导进行操作：
# 1. 选择网络接口（推荐选择 eth0 有线网卡）
# 2. 选择上游 DNS（可选择 Cloudflare 或保持默认，后续均可调整）
# 3. 确认静态 IP
# 4. 安装 Web 管理界面（推荐）
# 5. 务必记下最后终端输出的管理员初始密码

将局域网 DNS 指向 Pi-hole

# 方法 1：在路由器 DHCP 设置中修改 DNS（推荐）
  路由器管理后台 → DHCP 设置 → DNS 服务器
  主 DNS：192.168.3.2  (Pi-hole 的 IP)
  备用 DNS：追求极致拦截效果可留空，或填入第二个 Pi-hole 的 IP。
           若填写公共 DNS（如 1.1.1.1）虽然能在上线过渡期提高容灾能力，
           但终端设备可能会绕过 Pi-hole 走向公共 DNS，导致拦截失效。

  设备在下次续约 DHCP 时会自动将 Pi-hole 作为 DNS。
  手动强制续约：重新连接 Wi-Fi，或在 Linux 上运行 'sudo dhclient -r && sudo dhclient'

# 方法 2：单台设备手动指定 DNS（适合全网推广前的测试阶段）
  Windows：控制面板 → 网络适配器 → IPv4 属性 → 手动设置 DNS
  macOS：系统设置 → 网络 → 详细信息 → DNS → 手动添加
  Linux：修改 /etc/resolv.conf 或通过 NetworkManager 配置

# 方法 3：由 Pi-hole 兼任 DHCP 服务器（替代路由器 DHCP）
  Pi-hole 后台 → Settings → DHCP → Enable
  注意：必须先关闭路由器本身的 DHCP 服务，同一局域网内存在两个 DHCP 会导致网络冲突
  优势：主机名解析天然支持（设备会自动向 Pi-hole 注册自己的主机名）

黑名单规则管理

# Pi-hole 后台 → Adlists → Add new adlist

# 推荐黑名单规则源：
  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  # 默认规则 —— 包含 20 万+ 拦截域名

  https://blocklistproject.github.io/Lists/malware.txt
  # 恶意软件/病毒域名

  https://blocklistproject.github.io/Lists/tracking.txt
  # 隐私追踪与数据采集域名

# 添加规则源后操作：
  Tools → Update Gravity  （重新下载并编译更新所有黑名单库）

# 处理误杀（将合法网站加入白名单）：
  Pi-hole 后台 → Whitelist → Add domain
  示例：api.my-legitimate-service.com

# 实时查看拦截日志：
  Dashboard → Query Log  （实时 DNS 请求日志流，清晰显示拦截/放行状态）

配置 DNS-over-HTTPS (DoH) 上游

DNS-over-HTTPS 会对 DNS 请求进行加密，防止 ISP 监控你的域名解析行为。

# 安装 cloudflared（Cloudflare 官方出品的 DoH 代理工具）
# 推荐优先使用 Cloudflare 官方软件源安装，以支持软件包自动签名校验。
# 如果选择直接下载二进制文件，请锁定具体版本号并核对 Checksum 校验码。
CLOUDFLARED_VERSION="<pinned-version>"
curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
# 在安装前，请先对照 Cloudflare Release 说明核对文件的 checksum/签名。
sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# 创建 cloudflared 配置文件
sudo mkdir -p /etc/cloudflared
sudo tee /etc/cloudflared/config.yml << EOF
proxy-dns: true
proxy-dns-port: 5053
proxy-dns-upstream:
  - https://1.1.1.1/dns-query
  - https://1.0.0.1/dns-query
EOF

# 创建 systemd 系统服务
sudo cloudflared service install
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# 随后把 Pi-hole 的上游 DNS 指向本机的 DoH 代理：
# Pi-hole 后台 → Settings → DNS → Custom upstream DNS
# 填写：127.0.0.1#5053
# 取消勾选所有其他内置的上游 DNS 解析器

本地 DNS 记录

通过自定义域名直接访问内网服务（例如 nas.home.lan、grafana.home.lan）。

域名后缀提示： .home.lan 在 Homelab 圈子中广为使用且实际可用。
但依照 IETF 标准（RFC 8375），保留给本地私有网络使用的标准后缀是 .home.arpa —— 如果想遵循规范建议使用该后缀。请避免在 Pi-hole 中使用 .local 作为自定义域名，因为它会与 mDNS/Bonjour 协议产生冲突。

# Pi-hole 后台 → Local DNS → DNS Records

  Domain              IP
  nas.home.lan        192.168.30.10
  pi.home.lan         192.168.30.2
  grafana.home.lan    192.168.30.3
  proxmox.home.lan    192.168.30.4

# 内网任意设备均可直接解析访问：
  ping nas.home.lan        → 192.168.30.10
  http://grafana.home.lan  → 访问你的 Grafana 仪表盘

# 如需为子域名配置别名，可添加 CNAME：
  Pi-hole 后台 → Local DNS → CNAME Records
  Domain: portainer.home.lan → Target: pi.home.lan

故障排查

# 遇到误拦截
pihole -q example.com          # 查询域名是否被拦截以及具体被哪个规则列表拦截
pihole -w example.com          # 立即加白该域名

# DNS 完全无法解析
pihole status                  # 检查 pihole-FTL 服务运行状态
dig @192.168.3.2 google.com   # 直接向 Pi-hole 发起 DNS 测试请求

# 重启 Pi-hole DNS 服务
pihole restartdns

# 排查特定设备的请求日志
pihole -t                      # 实时查看全量请求日志流
# 或在 Web 管理后台的 Query Log 中按客户端 IP 进行过滤

# 手动更新 Gravity（刷新黑名单规则）
pihole -g

踩坑避坑指南

# 错误示范：单点依赖，缺乏故障回退机制
# 一旦 Pi-hole 崩溃或树莓派断电，全网设备直接无法上网
# 正确做法：搭建过程中准备好已记录的路由器备用配置，以便快速回滚
# 进阶推荐：运行两个 Pi-hole 节点做冗余备份；若要求严密拦截，切忌使用公共 DNS 作为备用 DNS

# 错误示范：在未配置静态 IP 的情况下安装 Pi-hole
# 一旦树莓派从 DHCP 重新获取到不同的 IP，所有设备的 DNS 全部失效
# 正确做法：先固定静态 IP，再进行 Pi-hole 安装

# 错误示范：未关闭路由器 DHCP 就直接开启 Pi-hole 的 DHCP
# 同一局域网内存在两个 DHCP 服务器，将导致 IP 分配冲突
# 正确做法：先禁用路由器 DHCP，再启用 Pi-hole DHCP

# 错误示范：长期不更新 Gravity（黑名单规则）
# 新的广告和恶意域名层出不穷 —— 规则库过期会导致拦截率大幅下降
# 正确做法：配置每周自动更新任务：pihole -g（或在 Settings → API 中开启）

最佳实践

• 在安装 Pi-hole 前，务必先为树莓派分配静态 IP 或在路由器中做好 DHCP 静态绑定
• 将 Pi-hole 设为主 DNS；若需高可用冗余且不想降低拦截标准，请部署第二个 Pi-hole，而非挂载公共 DNS
• 搭配 cloudflared 启用 DoH (DNS-over-HTTPS)，加密上游查询防嗅探
• 建议将 home.lan（或 home.arpa）作为内网域名，为所有自建服务配置本地 DNS 记录
• 定期巡检 Query Log 日志 —— 拦截记录能帮你洞察设备后台暗地里在发起哪些网络请求

相关 Skill

• homelab-network-setup
• homelab-vlan-segmentation
• homelab-wireguard-vpn