---

name: homelab-pihole-dns description: Pi-hole安装、屏蔽列表管理、DNS-over-HTTPS设置、DHCP集成、本地DNS记录，以及家庭网络DNS解析故障排除。 origin: community

家庭实验室 Pi-hole DNS

Pi-hole是一个网络级DNS广告拦截器，运行在树莓派或任何Linux主机上。网络上的每台设备都能自动获得广告和恶意域名拦截——无需浏览器扩展。

何时使用

• 在树莓派或Linux主机上安装Pi-hole
• 将Pi-hole配置为家庭网络的DNS服务器
• 添加或管理屏蔽列表
• 设置DNS-over-HTTPS（DoH）上游解析器
• 创建本地DNS记录（如 nas.home.lan、pi.home.lan）
• 排查安装Pi-hole后设备无法上网的问题
• 与DHCP并行或替代运行Pi-hole

Pi-hole工作原理

Normal flow (without Pi-hole):
  Device → requests ads.tracker.com → ISP DNS → real IP → ads load

With Pi-hole:
  Device → requests ads.tracker.com → Pi-hole DNS → blocked (returns 0.0.0.0) → no ad

All DNS queries go through Pi-hole first.
Pi-hole checks against blocklists.
Blocked domains return a null response — the ad/tracker never loads.
Allowed domains get forwarded to your upstream resolver (Cloudflare, Google, etc.).

安装

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 admin
    environment:
      TZ: "America/New_York"
      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # set via .env file or 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              # only needed if Pi-hole will serve DHCP

部署前将 <pinned-release-tag> 替换为当前Pi-hole发布标签。对于长期运行的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。

# Step 1: Assign a static IP (edit /etc/dhcpcd.conf on Pi OS)
sudo nano /etc/dhcpcd.conf
# Add at the bottom:
interface eth0
static ip_address=192.168.3.2/24
static routers=192.168.3.1
static domain_name_servers=192.168.3.1

# Step 2: Download and inspect the installer before running it.
curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
less pi-hole-install.sh
sudo bash pi-hole-install.sh

路由器DNS配置

安装后，将路由器的DNS服务器指向Pi-hole的IP：

Router DHCP settings → DNS Server: 192.168.3.2

所有设备在下次DHCP续约时将自动使用Pi-hole。

屏蔽列表管理

添加屏蔽列表

# 通过Web界面：Group Management → Adlists → Add
# 或通过命令行：
pihole -a adlist add https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts

# 更新gravity（应用新列表）
pihole -g

推荐屏蔽列表

• Steven Black统一列表（广告+恶意软件）
• OISD（优化的互联网安全域名列表）
• Firebog精选列表

白名单管理

# 添加白名单域名
pihole -w example.com

# 添加正则白名单
pihole --white-regex '(^|\.)example\.com$'

DNS-over-HTTPS设置

使用cloudflared作为DoH代理：

# 安装cloudflared
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-arm
sudo mv cloudflared-linux-arm /usr/local/bin/cloudflared
sudo chmod +x /usr/local/bin/cloudflared

# 配置为DNS代理
sudo cloudflared service install

配置Pi-hole使用 127.0.0.1#5053 作为上游DNS。

本地DNS记录

# Web界面：Local DNS → DNS Records
# 或编辑文件：
echo "192.168.3.10 nas.home.lan" | sudo tee -a /etc/pihole/custom.list
pihole restartdns

故障排除

设备无法上网

# 检查Pi-hole是否在运行
pihole status

# 检查DNS解析
dig @192.168.3.2 google.com

# 检查上游连接
dig @1.1.1.1 google.com

# 查看查询日志
pihole -t

常见问题

• DHCP冲突：确保只有一个DHCP服务器在运行
• 缓存问题：pihole restartdns 清除缓存
• 误拦截：检查查询日志，将域名加入白名单
• 性能：树莓派4可轻松处理100+设备的DNS查询