Maza 2026.08 介绍与选型指南

目标：在选型阶段说清 Maza 是什么、怎么工作、能解决什么问题、与 Pi-hole / AdGuard Home / Blocky / 手工维护 hosts 相比差在哪里。本文为认知篇，全部结论来自官方仓库、官方文档站与公开发布信息，检索日期 2026-10-25，不含本机实测数据；动手部署与验证过程见本专栏安装篇。

一、环境信息

• 文档类型：A1 介绍与选型指南（认知篇，仅联网溯源）
• 上游实体：tanrax/maza-ad-blocking（GitHub），作者 Andros Fenollosa（个人站点 andros.dev）
• 官方站点：https://maza-ad-blocking.andros.dev/
• 检索终端：Linux x86_64，网络可直连 GitHub、shields.io 与各项目官方站点
• 检索日期：2026-10-25
• 版本基线：上游未发布语义化版本 tag，本文以默认分支 master 最新提交 313491e（提交时间 2026-08-14）作为 2026.08 快照基线
• 许可证：Apache License 2.0（仓库侧栏 SPDX 标识 Apache-2.0）
• 仓库量化信息（检索当日仓库页 HTML 取证）：Star 1875、Watcher 20、Fork 72、创建于 2020-01-03、仓库未归档（isArchived=false）
• 脚本体量：maza 主脚本 233 行、5986 字节，纯 Bash，无编译产物、无第三方运行库

💡 说明：本文所有"检索当日"数据均指 2026-10-25 从 GitHub 仓库页、官方 README、各项目 tags/releases 源读取到的值。星数与版本会随时间变化，选型评审时请以当日官方页面为准。

二、软件概述

2.1 一句话定位

Maza 是一个用纯 Bash 编写的本地广告与追踪域名屏蔽工具。它不安装浏览器扩展、不运行常驻代理，而是把公开的广告域名清单转换成系统级的 hosts 记录，或转换成 dnsmasq 的 address=/域名/127.0.0.1 规则，从域名解析层让广告与追踪请求无法到达真实服务器。

官方 README 的定位描述是 "Like Pi-hole but local and using your operating system"，即"用操作系统自带能力实现的、本机版的 Pi-hole"。项目曾登上 Hacker News 首页（README 顶部保留讨论链接 news.ycombinator.com/item?id=22717650）。

2.2 实体消歧（重要）

互联网上存在多个叫 "Maza" 的项目与名称。本专栏的对象唯一是：

⚠️ 注意：初始甄别阶段的候选仓库名与实际上游不一致，已按官方仓库页与 README 更正为 tanrax/maza-ad-blocking。引用本项目时请使用该仓库地址，避免把同名项目的能力、版本与许可证套用到本文。

2.3 维护状态与发布节奏

• 维护状态：活跃。仓库未归档，默认分支 master 最近提交为 2026-08-14（"Add contribution guidelines to the README"），此前多次提交集中在 README、dnsmasq 支持与 macOS 兼容性改进。
• 发布节奏：不打版本 tag、不发 Releases。仓库 tags 页无任何 tag，/releases 也无发布记录。这意味着"Maza 的版本"实际等于"某个提交快照"。
• 对运维的影响：升级就是重新下载 master 上的脚本；要保证多机一致或可回滚，必须自行记录提交 SHA（如 313491e）并从该提交的 raw 地址下载。安装篇会给出按提交号固定版本的实测过程。
• 贡献方式：README 指向作者自建的贡献指南（git.andros.dev），并保留 IRC（Libera.Chat #maza-ad-blocking）与 Fediverse 联系方式。

💡 说明：本文标题中的 2026.08 不是上游发布的版本号，而是"2026 年 8 月最新提交快照"的约定写法，用于文档归档与实验复现。真实可核对的版本标识是提交 SHA 313491eea917009699976aeccc7db18235001e4d。

三、核心架构

3.1 组成与数据流

Maza 没有服务端进程，全部逻辑都是一次性的脚本执行。一次 maza update 的数据流固定为五步：

远程规则源（默认 pgl.yoyo.org/adservers）
        │  curl 下载纯文本域名清单
        ▼
$CONFIG/list  ── sed 清洗（去注释、去行尾空格、去 0.0.0.0/127.0.0.1 前缀）
        │            └── 按 $CONFIG/ignore 逐行删除
        │            └── 追加 $CONFIG/custom-domains
        ▼
/etc/hosts（带起止标记的屏蔽段）        $CONFIG/dnsmasq.conf（address=/域名/127.0.0.1）
        │                                        │
        ▼                                        ▼
操作系统解析器（getent / 浏览器）        dnsmasq（可选，提供通配子域拦截）

3.2 两条拦截路径

hosts 是操作系统级的静态名字映射，查询命中即返回，不经过网络；address=/域名/IP 是 dnsmasq 的配置指令，对匹配域名（含任意层级子域）直接应答指定 IP。两条路径可以同时启用，Maza 每次 update 会同时生成两份产物。

3.3 关键设计取舍

• 无守护进程：不监听端口、不占内存、不引入单点故障；代价是没有实时日志与统计面板。
• 幂等覆盖：/etc/hosts 中的屏蔽段由 ## MAZA - List ad blocking 与 ## END MAZA 两个标记包裹，每次 update 先删除旧段再写入新段，因此重复执行不会累积重复条目。
• 纯文本可审计：所有中间产物（list、dnsmasq.conf、ignore、custom-domains）都是可直接 cat、diff、纳入版本管理的文本。
• 配置目录可迁移：遵循 XDG_CONFIG_HOME，默认 $HOME/.config/maza/，便于把规则目录放到独立分区或集中备份。

四、功能特性

4.1 功能清单

4.2 能力边界

• 没有 Web 管理界面：查看、改规则都要编辑文本文件并重新执行 update。
• 没有统计与查询日志：不记录"哪个客户端查询了什么"。需要日志时必须额外启用 dnsmasq 的 log-queries，并自行解析日志文件。
• 没有按客户端/按时间段的策略：全机统一规则；AdGuard Home 的"客户端分组"、Pi-hole v6 的 Group Management 都不在其能力范围。
• 不提供加密 DNS：不实现 DoH/DoT/DoQ，也不做上游 DNS 转发管理，这部分完全交给 dnsmasq 或系统解析器。
• 规则格式单一：只接受"纯域名"清单（以及去掉 0.0.0.0/127.0.0.1 前缀的 hosts 行），不解析 AdBlock 语法（||domain^）与正则规则。

💡 技术拓展：DNS 层广告拦截有三类主流实现方式，选型时先分清自己需要哪一类。

方式	原理	代表实现	取舍
静态 hosts 改写	把域名写死到 127.0.0.1/0.0.0.0	Maza（hosts 模式）、手工维护 hosts	零依赖、零常驻；不支持通配、无日志、改一次只影响本机
DNS 黑洞（sinkhole）	自建 DNS 服务，对命中规则的查询直接应答空地址或 NXDOMAIN	Pi-hole、AdGuard Home	支持通配与全网设备、有统计；需常驻服务并接管 DNS
DNS 代理/转发过滤	作为 DNS 代理串联在解析链路中，按规则改写应答	Blocky、Maza（dnsmasq 模式）	灵活、可编排；同样需要常驻进程与 DNS 指向

Maza 的独特之处是把"静态 hosts"与"DNS 通配"两种形态放在同一个脚本里，按需启用，不需要引入完整的 DNS 服务平台。

五、快速开始（最小可用示例）

本节给出官方 README 的最小使用路径，用于建立整体印象。命令与预期输出引自官方文档，未在本文所在环境实测；逐步实测（含回显、排障与验证）见本专栏安装篇。

5.1 官方安装命令（Linux/macOS）

# 官方 README 给出的一行安装：下载脚本到当前目录，再放进 /usr/local/bin
curl -o maza https://raw.githubusercontent.com/tanrax/maza-ad-blocking/master/maza
sudo rm -rf /usr/local/bin/maza
chmod +x maza
sudo mv maza /usr/local/bin
# 官方建议：先备份 hosts，便于回滚
sudo cp /etc/hosts /etc/hosts.backup

5.2 启用与自检

sudo maza start     # 下载清单并写入 hosts（内部等价于 update + 启用提示）
sudo maza status    # 预期输出 ENABLED
curl googleadservices.com

官方 README 给出的命中预期是连接失败（域名被指向本机，本机 80 端口无服务）：

curl: (7) Failed to connect to googleadservices.com port 80 after 2 ms: Could not connect to server

5.3 官方声明的最小依赖

⚠️ 注意：官方 README 明确提醒先备份 /etc/hosts。Maza 会改写系统级解析文件，一旦规则源异常或自定义域名格式错误，可能影响本机域名解析；没有备份时回滚成本高。

六、适用场景与限制

6.1 适合的场景

1. 单机/少量设备的低成本去广告：一台 Linux 笔记本、开发机或树莓派，要求"装完即用、不常驻、不占资源"。
2. 已有 dnsmasq 的家庭网关：家里路由器/树莓派已经跑 dnsmasq，只需挂一个 conf-file 就能获得通配子域拦截，不必再部署 Pi-hole 全套服务。
3. 需要可审计、可版本化的规则：清单、白名单、自定义域名都是纯文本，适合纳入配置管理或 Git 仓库。
4. 临时/离线环境：脚本无依赖（只要 bash+curl），规则可预下载后内网分发。

6.2 不适合的场景

⚠️ 注意：Maza 的 stop 会清空 ~/.config/maza/dnsmasq.conf，但不会自动重载 dnsmasq。若已挂载该文件，停用后必须手动重启 dnsmasq 才会真正解除拦截；这一点在安装篇的实测中有完整回显。

七、同类选型对比

7.1 量化对比表（数据检索日期 2026-10-25）

7.2 关键差异解读

• 能力与复杂度正相关：Maza 用最少组件换取"零常驻"，代价是失去统计、分组、加密 DNS 与图形界面；Pi-hole/AdGuard Home 把 DNS 服务、Web 后台、日志与规则引擎打包在一起，功能完整但需要长期维护一个 DNS 服务。
• 规则规模不是越大越好：Maza 默认清单约 3.7k 域名，聚焦广告与追踪主域；Pi-hole/AdGuard 可挂 10 万级清单，但误杀排查成本同步上升。清单越大，越需要白名单与日志能力，而这正是 Maza 的短板。
• Blocky 与 Maza 的定位差异：两者都轻量，但 Blocky 是"可编程 DNS 代理"（YAML + API + 多上游），适合纳入自动化体系；Maza 是"一次性脚本"，适合不想维护服务的人。
• 手工 hosts 的唯一优势是可解释性：条目少、每条都能说清来源；一旦超过几十条，更新、去重、回滚都会变成负担，此时 Maza 的自动化收益开始显现。

7.3 选型建议

💡 说明：Maza 与 Pi-hole 不是替代关系而是"轻量档"与"平台档"。若后续需求从"本机去广告"升级为"全网 DNS 管理"，迁移路径通常是保留 Maza 的清单与白名单，改由 Pi-hole/AdGuard Home 托管同一批域名。

八、参考链接