Pi-hole · 基于自有 Linux 硬件的全网级广告 DNS 黑洞 · 网络广告过滤部署与使用全指南
项目仓库： https://github.com/pi-hole/pi-hole
开源协议：开源免费 · 定位：DNS sinkhole（DNS 黑洞） ·
组件：FTLDNS（轻量守护进程） + 命令行 pihole + 可选 Web
仪表盘 · 支持 IPv4 / IPv6 · 可选内置 DHCP 服务器
1 项目简介
Pi-hole 是一个运行在你自己的 Linux 硬件上的 DNS sinkhole（DNS 黑洞），在不安装任何客户端软件的情况下保护你的设备免受不需要的内容（广告、跟踪等）侵扰。把它设为路由器 / 设备的 DNS 服务器后，所有经过它的 DNS 查询都会按广告域名列表被拦截，从而在浏览器之外的位置（如手机 App、智能电视）也能屏蔽广告。
1.1 核心信息一览
| 项目项 | 内容 |
|---|---|
| 项目名称 | Pi-hole |
| 仓库地址 | github.com/pi-hole/pi-hole |
| 项目定位 | 全网级广告 / 跟踪 DNS 过滤（DNS sinkhole） |
| 核心组件 | FTLDNS（pi-hole/ftl）、`pihole` CLI、可选 Web 界面（pi-hole/web） |
| 安装方式 | 一键脚本 / 克隆仓库 / Docker（pi-hole/docker-pi-hole） |
| 访问入口 | http://pi.hole/admin/ 或
http://<IP>/admin/ |
| 支持协议 | IPv4 / IPv6 |
| 官方文档 | docs.pi-hole.net |
1.2 适用场景
- 家庭 / 办公室网络集中屏蔽广告与跟踪，覆盖所有设备（电视、手机、IoT）。
- 利用 DNS 缓存加速日常浏览。
- 作为可选 DHCP 服务器，让所有接入设备自动走 Pi-hole。
1.3 能力边界（官方口径）
- 安装后需把路由器 DHCP 的 DNS 指向 Pi-hole，或手动为每台设备设置 DNS；路由器不支持时可用 Pi-hole 内置 DHCP（先关掉路由器 DHCP）。
- 官方强调
curl | bash有争议（无法先审代码），提供了克隆仓库先审脚本的替代方式。
2 功能特性
- 易安装：对话框引导，十分钟内完成。
- 浏览器之外拦截：在手机 App、智能电视等非浏览器位置也拦截广告。
- DNS 缓存加速：缓存查询，提升日常浏览体验。
- 轻量：最低硬件 / 软件要求即可运行。
- 命令行
pihole：白名单 / 黑名单（allowlist / denylist）、正则、调试、实时日志、更新广告列表（gravity）、查询被屏蔽域名、启用 / 停用。 - Web 仪表盘：移动端适配、密码保护、图表、Top 列表、可过滤查询日志、长期统计。
- FTLDNS：轻量守护进程，提供统计数据与
API（
http://pi.hole/api/docs）。 - 可选 DHCP 服务器：让所有设备自动受保护。
- 可扩展：服务器级硬件可处理数亿查询。
3 官方界面预览
Web 仪表盘（可选）提供统计概览、图表、Top 域名 /
客户端列表、可排序查询日志与长期统计；访问地址
http://pi.hole/admin/（当 Pi-hole 是你的 DNS 时）或
http://<IP_ADDRESS>/admin/。
4 官方跳转链接汇总
| 类别 | 链接 | 说明 |
|---|---|---|
| 官网 | https://pi-hole.net | 官方站点 |
| 文档 | docs.pi-hole.net | 安装与使用文档 |
| 仓库主页 | https://github.com/pi-hole/pi-hole | 安装脚本 |
| 前置要求 | docs.pi-hole.net/main/prerequisites | 硬件 / 系统要求 |
| 安装后配置 | docs.pi-hole.net/main/post-install | 网络配置 |
| FTL 守护进程 | pi-hole/ftl | 核心守护进程 |
| Web 界面 | pi-hole/web | 仪表盘 |
| Docker 镜像 | pi-hole/docker-pi-hole | 官方 Docker 部署 |
| CLI 文档 | docs.pi-hole.net/core/pihole-command | pihole 命令 |
| 社区论坛 | discourse.pi-hole.net | FAQ 与讨论 |
5 前置要求与服务器配置
5.1 软件前提
- 一台 Linux 机器（树莓派或服务器均可）；具体要求见 前置要求。
- Docker（可选）：用官方 Docker 镜像部署。
5.2 硬件建议
- 官方称资源占用低；服务器级硬件可处理海量查询。
5.3 端口与资源
- 提供 DNS 服务（UDP/53）；Web 仪表盘默认端口见安装后配置。
6 方式一：一键脚本 / 克隆安装（推荐）
# 一键自动安装（快速但无法先审代码）
curl -sSL https://install.pi-hole.net | bash
# 或克隆仓库后先审脚本再运行（官方推荐可审计方式）
git clone --depth 1 https://github.com/pi-hole/pi-hole.git Pi-hole
cd "Pi-hole/automated install/"
sudo bash basic-install.sh7 方式二：Docker 部署
参考官方 pi-hole/docker-pi-hole 使用官方 Docker 镜像部署。
8 配置项说明
- 网络配置：安装后把路由器 DHCP 的 DNS 指向 Pi-hole；路由器不支持时用内置 DHCP（先关路由器 DHCP）。
- CLI
常用动作：
pihole enable/disable、pihole updateGravity（更新广告列表）、pihole tail（实时日志）、pihole -q <domain>（查询是否被屏蔽）、allowlist/denylist。 - API：
http://pi.hole/api/docs；示例curl --connect-timeout 2 -ks "https://pi.hole/api/stats/summary" -H "Accept: application/json"。
9 常用运维命令
- 查看版本 / 状态：
pihole status - 更新广告列表：
pihole updateGravity - 实时日志：
pihole tail - 查询域名：
pihole -q <domain> - 临时停用：
pihole disable（或enable） - 调试：
pihole debug
10 常见故障排查
- 设备没走过滤：确认路由器 / 设备 DNS 已指向
Pi-hole；用
pihole tail观察是否有查询进来。 - 域名误屏蔽：用
pihole -q <domain>定位命中列表，再用 allowlist 放行。 - Dashboard 打不开：确认访问
http://<IP>/admin/，密码正确。 - 求助：先查 Discourse FAQ。
11 风险与合规说明
- 许可证：开源免费软件，由志愿者维护，欢迎捐赠 / GitHub Sponsors 支持。
- 隐私与责任：Pi-hole 把 DNS 查询集中到你自己控制的设备，提升隐私；但 DNS 拦截可能误拦正常服务，需自行维护白名单。
- 本文整理自官方 README，命令与配置以官方文档最新说明为准；不包含 star 数等动态数据。