
关于
Pi-hole 安装、屏蔽列表管理、DNS-over-HTTPS 设置、DHCP 集成、本地 DNS 记录和家庭网络 DNS 解析故障排除。
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查询
兼容工具
Claude CodeCursor
标签
前端开发
