目录
Pi-hole 是什么？
Pi-hole 是一个网络级的广告拦截器。它运行在你的路由器或一台小型服务器上，充当整个家庭网络的 DNS 服务器——任何通过你家 Wi-Fi 连网的设备（手机、电脑、电视、智能家居），广告请求在 DNS 解析阶段就会被拦截。
一句话概括：装一次，全家受益，连智能电视的广告都能干掉。
它的名字里的「Pi」来自最初推荐运行在树莓派（Raspberry Pi）上，但实际上任何 Linux 设备都能跑。
它是怎么工作的？
你的手机 → 打开一个 App → App 请求加载广告
↓
查询 DNS：ad.doubleclick.net？
↓
路由器 → Pi-hole DNS
↓
Pi-hole 查广告黑名单：命中！
↓
返回 0.0.0.0（无效 IP）
↓
广告加载失败，页面干干净净
因为广告拦截发生在 DNS 层面，所以它比浏览器插件（如 AdBlock）更强：
| 对比 | 浏览器去广告插件 | Pi-hole |
|---|---|---|
| 覆盖范围 | 只限浏览器 | 所有联网设备 |
| 对 App 广告 | ❌ 无能为力 | ✅ 有效 |
| 对智能电视广告 | ❌ 无能为力 | ✅ 有效 |
| 对 IoT 设备追踪 | ❌ 无能为力 | ✅ 有效 |
| 性能影响 | 占用浏览器内存 | 几乎无感（延迟 < 1ms） |
准备工作
| 条件 | 说明 |
|---|---|
| 一台 24 小时运行的设备 | 树莓派、NAS、软路由、云服务器、旧电脑均可 |
| 静态 IP | 这台设备需要一个固定的局域网 IP |
| 能改路由器 DNS 设置 | 大部分家用路由器都支持 |
| 基本 Linux 操作能力 | Docker 基础即可 |
💡 最省钱方案：闲鱼上 50 块钱的树莓派 Zero 2 W 完全够用。或者直接用你已有的 NAS / 软路由 / 常开的 Linux 小主机。
Docker 一键部署
docker run 方式
docker run -d \
--name pihole \
--restart unless-stopped \
-e TZ="Asia/Shanghai" \
-e WEBPASSWORD="设置一个管理密码" \
-e PIHOLE_DNS_="223.5.5.5;119.29.29.29" \
-p 53:53/tcp \
-p 53:53/udp \
-p 80:80/tcp \
-v /opt/pihole/etc-pihole:/etc/pihole \
-v /opt/pihole/etc-dnsmasq.d:/etc/dnsmasq.d \
pihole/pihole:latest
参数说明：
| 参数 | 含义 |
|---|---|
TZ |
时区，国内填 Asia/Shanghai |
WEBPASSWORD |
管理面板登录密码 |
PIHOLE_DNS_ |
上游 DNS，这里用了阿里 DNS 和腾讯 DNS |
-p 53:53 |
DNS 端口（必须同时开放 TCP 和 UDP） |
-p 80:80 |
Web 管理面板端口 |
Docker Compose 方式（推荐）
version: "3.8"
services:
pihole:
image: pihole/pihole:latest
container_name: pihole
restart: unless-stopped
environment:
TZ: "Asia/Shanghai"
WEBPASSWORD: "your-strong-password"
PIHOLE_DNS_: "223.5.5.5;119.29.29.29"
ports:
- "53:53/tcp"
- "53:53/udp"
- "80:80/tcp"
volumes:
- ./etc-pihole:/etc/pihole
- ./etc-dnsmasq.d:/etc/dnsmasq.d
cap_add:
- NET_ADMIN
docker-compose up -d
验证是否运行成功
# 查看日志确认服务已启动
docker logs pihole | tail -20
如果你没有通过 WEBPASSWORD 环境变量设置密码，日志末尾会显示随机生成的密码。设置过的话直接用你设的密码，浏览器访问 http://你的设备IP/admin 登录管理面板。
⚠️ 端口 53 冲突问题： 有些系统的 systemd-resolved 会占用 53 端口。如果容器起不来，先执行：
sudo systemctl stop systemd-resolved sudo systemctl disable systemd-resolved注意：停止 systemd-resolved 后主机自身的 DNS 解析会受影响。如果你是通过 SSH 连接服务器，建议先确认有其他 DNS 可用（比如在
/etc/resolv.conf中手动指定）。
配置路由器指向 Pi-hole
部署完 Pi-hole 后，你需要让家里的所有设备都走 Pi-hole 做 DNS 解析。有两种方式：
方式一：修改路由器 DHCP 的 DNS（推荐）
登录路由器管理后台 → 找到 DHCP 服务器设置 → 把主 DNS 服务器改为 Pi-hole 的 IP 地址。
以常见路由器为例：
- TP-Link / 小米 / 华为路由器： 网络设置 → DHCP 服务器 → DNS 服务器填 Pi-hole 的 IP
- OpenWrt / 软路由： 网络 → 接口 → LAN → DHCP 服务器 → 高级设置
- 华硕路由器： 内部网络 → DHCP 服务器 → DNS 服务器
改完后，所有设备断开 Wi-Fi 重连一次，广告就没了。
方式二：手动设置单台设备
如果暂时不想改路由器，可以先在自己手机上测试效果：
- iPhone： 设置 → Wi-Fi → 点当前网络的 ⓘ → 配置 DNS → 手动 → 添加 Pi-hole 的 IP
- Android： 设置 → Wi-Fi → 长按当前网络 → 修改网络 → 高级选项 → DNS 1 填 Pi-hole 的 IP
- Windows： 网络设置 → 更改适配器选项 → 右键网卡 → 属性 → IPv4 → DNS 填 Pi-hole IP
管理面板与进阶设置
Pi-hole 的管理面板非常直观，几个核心页面：
Dashboard（仪表盘）
展示总查询数、拦截数、拦截比例、客户端排行等。一个正常运行的 Pi-hole，拦截率通常在 15%-30% 之间。如果太低说明广告规则不够，太高说明可能误杀了正常网站。
Query Log（查询日志）
实时显示每一条 DNS 请求，可以按时间、客户端、域名过滤。调试白名单的好帮手。
Adlists（广告规则列表）
默认自带一个规则列表，包含约 10 万个广告域名。你可以添加更激进的列表：
# 中文广告过滤
https://raw.githubusercontent.com/AdguardTeam/AdguardFilters/master/ChineseFilter/sections/adservers.txt
https://raw.githubusercontent.com/Cats-Team/AdRules/main/dns.txt
# 更全面的拦截
https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
💡 规则不是越多越好，太多会拖慢 DNS 响应。建议 3-5 个精选列表即可。
白名单：让该放的过去
Pi-hole 偶尔会误拦正常内容（比如淘宝的营销链接、微信中的跳转链接、某些 App 的统计服务）。这时需要加白名单。
在 Pi-hole 管理面板 → Whitelist → 添加域名即可。常见需要加白的域名：
# 微信相关
mp.weixin.qq.com
res.wx.qq.com
# 淘宝 / 拼多多链接跳转
click.taobao.com
uland.taobao.com
p.pinduoduo.com
# 抖音 / 头条
lf3-cdn-tos.bytego.com
💡 不需要一次性加很多——正常使用过程中如果发现某个 App 或网页异常，去 Query Log 里找到被拦的域名，加白即可。这是一个渐进调优的过程。
常见问题
Q: 我用路由器改了 DNS，为什么还有广告？
三个可能：① 手机/电脑有 DNS 缓存，重启设备或等几分钟；② 浏览器装了 DoH（DNS-over-HTTPS），绕过了系统 DNS——去浏览器设置里关掉「安全 DNS」；③ 部分 App 用了 IP 直连而非域名，DNS 层面无法拦截。
Q: Pi-hole 会拖慢网速吗？
基本不会。DNS 查询只是在你打开网页的瞬间多走了一小步查表操作（< 1ms 延迟），之后所有数据流量都直接走你的宽带，不过 Pi-hole。你感受到的不是变慢而是变快——因为广告资源被毙掉了，页面加载更快。
Q: Pi-hole 本身挂了怎么办？全家断网？
这确实是单点故障风险。解决方案：路由器 DNS 设置里填两个 DNS——主 DNS 是 Pi-hole，备用 DNS 填 223.5.5.5（阿里 DNS）。这样 Pi-hole 挂了会自动切到阿里 DNS，只是暂时失去去广告效果。或者干脆跑两台 Pi-hole 做高可用。
Q: 和 AdGuard Home 比哪个好？
功能类似，都是 DNS 级去广告。简要对比：
| 维度 | Pi-hole | AdGuard Home |
|---|---|---|
| 安装 | 简单 | 更简单（更轻量） |
| 界面 | 经典、信息密度高 | 现代、更直观 |
| 上游配置 | 手动改文件 | 管理面板直接改 |
| DoH/DoT | 需额外配置 | 内置支持 |
| 社区生态 | 最老牌、资料最多 | 快速增长中 |
两者都是好选择，如果你想要零折腾，AdGuard Home 可能更适合新手。Pi-hole 胜在社区庞大，遇到问题网上几乎一定有答案。
Q: 树莓派关了，想重启 Pi-hole 服务？
docker-compose up -d
数据都在挂载的目录里，重启后一切如初。
技术博客 · 欢迎分享 · 如有疑问欢迎交流