Holeberry：macOS菜单栏一键管理Pi-hole的开源神器

对于长期使用 Pi-hole 进行网络级广告拦截的用户来说，最烦人的莫过于——每次只是想查看一下状态、或临时解封某个网站，都得打开浏览器登录 Web 管理界面。开发者 Pedro Vieira 显然深有同感，于是他打造了 Holeberry：一款原生的 macOS 菜单栏应用，专为管理 Pi-hole 而生。它完全免费、开源（MIT 协议），目前已在 GitHub 上发布。

Pi-hole 是什么？为什么需要专属管理工具

Pi-hole 是一个基于 DNS 层面的网络级广告拦截工具，最初设计运行在 Raspberry Pi（树莓派）上，后来扩展到支持各种 Linux 发行版和 Docker 容器部署。它的工作原理是充当局域网的 DNS 服务器，当设备请求解析某个已知广告或追踪域名时，Pi-hole 会返回一个空地址（如 0.0.0.0 或 NXDOMAIN），从而在网络层面直接阻止广告内容加载。

这种技术在网络安全领域被称为 DNS Sinkhole（DNS 黑洞）。要理解它的工作方式，需要了解 DNS 解析的基本流程：当你在浏览器中输入一个网址（如 example.com）时，设备首先需要向 DNS 服务器查询该域名对应的 IP 地址，拿到 IP 后才能建立网络连接并加载内容。Pi-hole 正是利用了这一必经环节——它截获 DNS 查询请求，将其与维护的域名黑名单进行比对。如果请求的域名（如 ads.tracking-company.com）匹配黑名单中的条目，Pi-hole 不会将请求转发给上游 DNS 服务器（如 Cloudflare 的 1.1.1.1 或 Google 的 8.8.8.8），而是直接返回一个无效地址，使得广告内容的网络请求在最初阶段就被终止。这意味着广告数据根本不会被下载到设备上，不仅拦截了广告，还节省了带宽。

与浏览器插件（如 uBlock Origin）不同，Pi-hole 的拦截对整个网络中的所有设备生效——包括智能电视、IoT 设备和手机应用中的广告——而无需在每台设备上单独安装软件。浏览器插件的工作原理是在页面渲染阶段通过内容过滤规则（如 EasyList）识别并隐藏或阻止广告元素的加载，它只能作用于浏览器环境内，对原生应用中嵌入的广告 SDK、智能电视的开屏广告或 IoT 设备的遥测数据束手无策。而 Pi-hole 作为网络基础设施层面的拦截方案，只要设备使用了局域网内的 Pi-hole 作为 DNS 服务器，其所有 DNS 查询都会经过过滤——这就是"网络级"拦截的含义。

正因为 Pi-hole 是一个运行在服务器端的服务，用户日常管理它的唯一官方途径就是通过浏览器访问 Web 管理界面。这对于偶尔调整配置尚可接受，但对于频繁需要查看状态、解封域名等高频操作来说，体验就相当笨重了。这正是 Holeberry 存在的意义。

Holeberry 的设计初衷：告别繁琐的 Web 管理界面

Holeberry 的诞生逻辑非常清晰：把高频操作从繁琐的 Web UI 中解放出来，收纳进触手可及的菜单栏。

macOS 的菜单栏应用（Menu Bar App）是 Apple 生态中一种独特且成熟的 UI 范式。与占据 Dock 栏位置的完整窗口应用不同，菜单栏应用以一个小图标的形式常驻于屏幕顶部的菜单栏右侧区域，点击后展开一个轻量级的下拉面板。这种形态特别适合两类场景：一是需要持续展示状态信息的监控类工具（如网速监测、CPU 温度、VPN 状态），二是偶尔需要快速触发某个操作的效率工具（如剪贴板管理器、窗口管理器）。Pi-hole 的日常管理需求——查看拦截状态和快速执行白名单操作——恰好完美契合这一范式。macOS 上诸多广受好评的工具如 Bartender、iStat Menus、Little Snitch 等都采用了这种形态，用户已经形成了"菜单栏 = 快速访问"的使用习惯。

开发者在 Reddit 上坦言，他在动手之前调研过市面上现有的 Pi-hole 伴侣应用，但发现问题不少——有些项目已经停止维护，有些界面陈旧，更关键的是它们并不能满足他日常真正需要的功能。

于是，他把自己最常用的几个需求直接做成了 Holeberry 的核心：让两台 Pi-hole 实例保持同步、只解封当前浏览器标签页而非关闭整个网络的拦截、以及能够一眼扫过拦截状态。这种"从自身痛点出发"的开发路径，往往能造就使用体验极佳的小工具。

Holeberry 核心功能详解

菜单栏常驻，Pi-hole 状态一目了然

Holeberry 常驻在 macOS 菜单栏中，随时显示当前拦截状态、总查询数和被拦截数量。无需打开浏览器，只需瞥一眼菜单栏即可掌握网络防护情况。

双实例同步管理

对于运行主备两台 Pi-hole 的用户，Holeberry 支持同时管理最多两个实例。所有操作（拦截/解封/加入白名单）都会同步应用到两台设备上，避免两者配置"漂移"不一致——这是很多 Pi-hole 高可用部署用户长期头疼的问题。

要理解这个功能的价值，需要了解 Pi-hole 双实例部署的背景。在家庭或小型办公网络中，DNS 服务是所有网络访问的基础——如果唯一的 Pi-hole 宕机，所有设备都将无法正常解析域名，等同于整个网络"断网"。因此，许多进阶用户会部署两台 Pi-hole 实例（通常分别运行在两台树莓派或两个 Docker 容器中），在路由器的 DHCP 设置中同时指定两个 DNS 地址，实现冗余。

从技术层面来看，当路由器通过 DHCP 协议向网络中的设备分配网络配置时，会同时下发主 DNS 和备用 DNS 地址。当设备发起 DNS 查询时，操作系统通常会优先使用主 DNS 服务器，但如果主服务器在一定时间内（通常为几秒）未响应，系统会自动切换到备用 DNS 服务器。这种机制确保了即使一台 Pi-hole 发生故障，网络中的设备仍能正常访问互联网。值得注意的是，不同操作系统对多 DNS 服务器的处理策略有所不同——例如 macOS 和 iOS 可能会并行查询多个 DNS 服务器并使用最先返回的结果，而部分 Linux 发行版则严格按照顺序尝试。无论采用何种策略，双实例部署都能显著提高 DNS 服务的可用性。

但这种部署带来一个持续性痛点：两台 Pi-hole 的白名单、黑名单和自定义 DNS 记录需要手动保持一致。社区虽然开发了 Gravity Sync、Orbital Sync 等工具来同步 Gravity 数据库，但日常的临时白名单操作仍然需要在两个管理界面上分别执行。Holeberry 的双实例同步管理功能正是针对这一场景设计，一次操作、两台生效，彻底消除手动同步的负担。

定时禁用拦截与自动恢复

用户可以全局禁用广告拦截，并设置一个倒计时（或选择无限期禁用）。菜单栏会实时显示倒计时，到期后自动重新启用拦截。这一设计既满足了临时关闭拦截的需求，又避免了"忘记打开"导致防护长期失效的尴尬。

一键解封当前浏览器标签页

这是开发者本人最推崇、也用得最多的功能：当某个网站因 Pi-hole 拦截而无法正常访问时，Holeberry 可以一键解封当前浏览器标签页对应的站点，而无需关闭整个网络的拦截。它支持 Safari、Chrome/Chromium、Firefox/Zen 等主流浏览器。这种精准解封的思路，比传统的"全局禁用几分钟"要优雅得多。

从技术实现角度来看，这一功能需要 Holeberry 完成几个步骤：首先，通过 macOS 的辅助功能 API 或浏览器提供的 AppleScript/Accessibility 接口获取当前活跃浏览器标签页的 URL；然后从 URL 中提取域名部分；接着通过 Pi-hole 的 API 将该域名添加到白名单中。这比简单地全局禁用 Pi-hole 要精细得多——全局禁用意味着整个网络中所有设备的所有广告拦截都会暂停，而单域名白名单只放行特定站点的请求，其他所有拦截规则继续生效。

进阶能力与安全性设计

浏览最近拦截记录并快速加白

开发者特别强调，Holeberry 允许用户直接从菜单中浏览最近被拦截的域名，并即时将其加入白名单或解封。这一功能让排查"哪个域名被误拦"变得异常直观。

误拦（false positive）是 Pi-hole 用户面临的常见问题。由于广告拦截列表是由社区维护的，有时会出现过度拦截的情况——某些网站的正常功能所依赖的域名被错误地列入了黑名单。例如，一些网站使用 CDN（内容分发网络）域名来加载关键的 JavaScript 文件或字体资源，如果这些 CDN 域名恰好与某个广告追踪域名共享同一个子域名模式，就可能被黑名单规则误伤。传统的排查方式是：用户发现网站异常 → 打开 Pi-hole Web 管理界面 → 进入查询日志页面 → 筛选出被拦截的域名 → 逐一判断哪个是导致问题的域名 → 手动加入白名单。Holeberry 将这一流程压缩到菜单栏的几次点击中，大幅提升了排查效率。

远程触发 Gravity 列表更新

用户可以直接从菜单栏触发 Gravity 更新，并在所有服务器上同步执行，无需逐一登录管理界面。

Gravity 是 Pi-hole 的核心拦截列表管理机制。Pi-hole 维护着一个或多个远程订阅的域名黑名单（blocklist），这些列表由社区维护，包含数十万甚至数百万个已知的广告、追踪和恶意域名。知名的列表源包括 Steven Black 的统一主机列表（整合了多个来源，包含超过 17 万个域名）、Firebog 推荐的精选列表集合，以及针对特定区域或用途的专项列表（如反恶意软件列表、反加密挖矿列表等）。

当用户执行 Gravity 更新（等同于在服务器上运行 pihole -g 命令）时，Pi-hole 会从所有已订阅的远程源重新下载最新的域名列表，合并去重后写入本地的 Gravity 数据库（在 v6 中为 SQLite 数据库）。这个过程类似于杀毒软件更新病毒库——定期更新 Gravity 列表能确保 Pi-hole 能拦截最新出现的广告和追踪域名。广告行业和追踪技术公司会不断注册新域名来绕过现有的拦截规则，因此保持列表的及时更新对于维持拦截效果至关重要。Pi-hole 默认每周日凌晨自动执行一次 Gravity 更新，但用户也可以在订阅了新的列表源后手动触发更新。

过去，用户要么手动 SSH 登录服务器执行命令，要么在 Web 界面上操作，而 Holeberry 将这一操作简化为菜单栏上的一次点击。

隐私与安全保障

在安全方面，Holeberry 做得相当到位：

• 应用已通过付费开发者账号完成完整公证（notarized），安装无需绕过 macOS 的安全限制。macOS 的公证（Notarization）是 Apple 自 macOS 10.14.5 起引入的安全机制——开发者在分发应用前，需要将构建好的应用提交给 Apple 的自动化服务进行安全扫描，Apple 确认应用不包含已知恶意软件后会签发一个"票据"（ticket）。用户下载并运行经过公证的应用时，macOS 的 Gatekeeper 会在线验证该票据，确认通过后才允许运行。未经公证的应用在打开时会弹出安全警告，用户需要手动到"系统设置 > 隐私与安全性"中点击"仍然打开"才能运行。Holeberry 完成了完整的签名与公证流程，意味着用户可以像安装来自 App Store 的应用一样顺畅地使用它。值得一提的是，公证流程要求开发者持有 Apple Developer Program 的付费会员资格（每年 99 美元），这对于一个完全免费的开源项目来说是开发者自掏腰包的投入，体现了对用户体验和安全性的重视。

• 凭据全部存储在 Keychain 钥匙串中，不会以任何形式写入磁盘。Keychain（钥匙串）是 macOS 和 iOS 内置的系统级凭据管理器，由 Apple 的安全框架提供，使用 AES-256-GCM 加密算法对存储的数据进行加密保护。应用通过 Keychain Services API 可以安全地存储密码、API 令牌、证书等敏感信息，这些数据以加密形式保存在系统钥匙串数据库中，并受用户登录密码和（在支持的硬件上）Secure Enclave 芯片保护。与将凭据以明文或简单编码形式写入配置文件的做法相比，使用 Keychain 存储意味着即使攻击者获得了磁盘访问权限，也无法直接读取这些敏感信息。对于 Holeberry 而言，它需要存储的敏感信息主要是 Pi-hole 实例的 API 令牌（API Token）——这个令牌等同于 Pi-hole 管理界面的登录凭证，拥有它就可以控制 Pi-hole 的所有设置。如果这个令牌被泄露，攻击者可以远程禁用你的广告拦截、修改 DNS 设置甚至将流量重定向到恶意服务器。因此，将其安全地存储在 Keychain 中而非明文配置文件中，是一个关乎网络安全的重要设计决策。

• 支持无密码的 Pi-hole 实例。

对于注重隐私的 Pi-hole 用户群体而言，这些细节无疑加分不少。

系统要求与下载方式

Holeberry 要求 macOS 14（Sonoma）及以上版本，主要支持 Pi-hole v6，同时兼容 v5（但测试较少）。

值得注意的是，Pi-hole v6 是 2025 年 2 月正式发布的重大版本更新，经历了长达数年的开发周期。相较 v5，v6 在架构层面进行了根本性的重构。最显著的变化是用嵌入式的 FTL（Faster Than Light）Web 服务器取代了之前依赖的 lighttpd + PHP 技术栈。在 v5 中，Web 管理界面由 lighttpd 提供 HTTP 服务，PHP 处理后端逻辑，而 FTL 进程（Pi-hole 的核心 DNS 解析引擎）通过共享内存和套接字与 PHP 通信。这种多组件架构虽然功能完善，但带来了较高的内存占用和维护复杂性——在树莓派 Zero 等资源受限的设备上尤为明显。v6 将 Web 服务器直接嵌入 FTL 进程中，消除了对 lighttpd 和 PHP 的依赖，不仅大幅降低了资源占用，也简化了安装和升级流程。

在 API 方面，v5 的"API"实际上是一组非正式的 PHP 端点（如 /admin/api.php?summary），缺乏标准化的认证机制和一致的响应格式。v6 引入了全新的 RESTful API，支持基于会话（session-based）的认证，提供结构化的 JSON 响应，并覆盖了几乎所有管理功能。这意味着像 Holeberry 这样的第三方客户端应用可以通过标准化的 API 接口与 Pi-hole 进行可靠的交互，而不再需要依赖脆弱的 PHP 端点解析。Holeberry 优先适配 v6 的新 API，意味着它能充分利用新版本带来的性能和功能改进。

项目已在 GitHub 开源，地址为 github.com/pedrovieira/Holeberry。开发者表示欢迎社区提交功能请求和 Bug 反馈。

关于 MIT 开源协议

Holeberry 采用的 MIT 协议（MIT License）是目前使用最广泛的开源许可证之一，以其极高的宽松度著称。MIT 协议的核心条款极为简单：任何人都可以自由地使用、复制、修改、合并、发布、分发、再许可和/或出售该软件的副本，唯一的条件是在软件的所有副本或主要部分中包含原始的版权声明和许可声明。与 GPL（GNU 通用公共许可证）要求衍生作品也必须开源不同，MIT 协议允许他人将代码整合到闭源商业项目中，不强制要求开源。对于用户而言，MIT 协议意味着完全的使用自由和法律确定性；对于潜在的社区贡献者而言，它降低了参与门槛——贡献的代码不会被复杂的许可条款所约束。在 macOS 开发生态中，Swift 语言本身以及大量的 Apple 官方示例代码也采用类似的宽松许可，使得 Holeberry 的代码可以被其他开发者轻松借鉴和复用。

总结：Pi-hole macOS 用户值得一试的管理工具

Holeberry 是一个典型的"挠自己痒处"（scratch your own itch）的优秀开源项目。它没有堆砌花哨功能，而是聚焦于 Pi-hole 用户最真实的日常痛点——快速查看状态、精准解封单个页面、多实例同步管理。对于已经在使用 Pi-hole 的 macOS 用户来说，这样一款轻量、原生、免费且注重隐私的菜单栏工具，几乎没有理由不试一试。而它免费开源的特性，也让社区有机会共同推动其持续演进。

核心要点