Ubuntu 22.04 安装 Maza 2026.08 指南

目标：在 Ubuntu 22.04 服务器上从零安装 Maza 2026.08（master 提交 313491e 快照），完成 hosts 模式启用与拦截验证，并可选集成 dnsmasq 获得通配子域与局域网级拦截；同时给出固定版本、卸载清理与排障方法。全部命令已在 Ubuntu 22.04.5 LTS（x86_64）实测通过，回显逐行照抄。Maza 的定位与选型对比见 《Maza 2026.08 介绍与选型指南》。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS (Jammy Jellyfish)，x86_64
• 运行依赖：GNU bash 5.1.16(1)-release、curl 7.81.0、GNU sed（系统自带）
• 可选组件：dnsmasq 2.91-0ubuntu0.22.04.2（通配子域与局域网拦截用）、bind9-dnsutils（DiG 9.18.39，验证用）
• 软件基线：Maza 2026.08 快照 = master 分支提交 313491eea917009699976aeccc7db18235001e4d（2026-08-14），单文件脚本 233 行 / 5986 字节，SHA-256 为 bdfb8fda1c5523cf5ffa227f5efbda63fef3360abc39b299b8c7061ad486b41a
• 演示机器：服务器 A（10.89.56.4，安装 Maza + dnsmasq）、客户端 B（同网段，验证局域网拦截）
• 执行账号：root（Maza 需改写 /etc/hosts，必须 root 或 sudo）
• 实测日期：2026-10-25

二、前置条件

安装前确认以下四项，缺一不可：

1. root 权限：Maza 要改写 /etc/hosts 并（可选）操作 dnsmasq，全程以 root 执行。
2. bash ≥ 4.0 与 curl：Ubuntu 22.04 自带，实测版本如下：

$ bash --version | head -1
GNU bash, version 5.1.16(1)-release (x86_64-pc-linux-gnu)
$ curl --version | head -1
curl 7.81.0 (x86_64-pc-linux-gnu) libcurl/7.81.0 OpenSSL/3.0.2 zlib/1.2.11 brotli/1.0.9 zstd/1.4.8

3. 先备份 /etc/hosts：Maza 会直接改写该文件，备份是一键回滚的底线（官方 README 也明确提醒）。
4. 网络可达性：方案 A/B 需从 raw.githubusercontent.com 下载脚本（约 6 KB）；首次启用还需可达默认规则源 pgl.yoyo.org。完全离线环境用方案 B 的内网分发形态。

⚠️ 注意：macOS 需额外 brew install gnu-sed（脚本检测到 Darwin 会改用 gsed）；本文只覆盖 Ubuntu 22.04。

三、版本选型说明

Maza 上游不打版本 tag、不发 Releases（详见 《Maza 2026.08 介绍与选型指南》第二章），"版本"即某个提交快照。安装时只有两种取法：

本文以 2026.08 快照（提交 313491e）为基线，实测该提交的脚本 SHA-256：

bdfb8fda1c5523cf5ffa227f5efbda63fef3360abc39b299b8c7061ad486b41a

💡 说明：实测当日 master 与 313491e 内容一致（两者下载后 SHA-256 相同）。生产环境建议始终用方案 B 固定 SHA，避免"今天装的和昨天装的不是同一份代码"。

四、在线安装方案（A：官方脚本直连）

官方 README 的标准安装路径：下载脚本 → 校验 → 放入 /usr/local/bin。

4.1 备份 hosts

$ cp /etc/hosts /etc/hosts.backup
$ ls -l /etc/hosts.backup
-rw-r--r-- 1 root root 170 Oct 25 16:02 /etc/hosts.backup

4.2 下载脚本

$ cd /root
$ curl -o maza -w 'http_code=%{http_code} size=%{size_download}\n' https://raw.githubusercontent.com/tanrax/maza-ad-blocking/master/maza
http_code=200 size=5986

⚠️ 注意：raw.githubusercontent.com 直连在实测当日偶发连接重置（curl 返回 exit 56、http_code=000），重试即可恢复（实测最多重试 3 次后成功下载）。反复失败时检查本机代理或出口网络。

4.3 校验与安装

下载后先校验哈希与语法，再安装到 PATH：

$ sha256sum /root/maza
bdfb8fda1c5523cf5ffa227f5efbda63fef3360abc39b299b8c7061ad486b41a  /root/maza
$ wc -l /root/maza
233 /root/maza
$ bash -n /root/maza && echo syntax_exit=$?
syntax_exit=0
$ chmod +x /root/maza
$ rm -rf /usr/local/bin/maza   # 官方步骤：清掉可能的旧版本
$ mv /root/maza /usr/local/bin/maza
$ ls -l /usr/local/bin/maza
-rwxr-xr-x 1 root root 5986 Oct 25 16:08 /usr/local/bin/maza

bash -n 语法检查通过（exit 0）、哈希与第三章基线一致，安装完成。直接输入 maza --help 即可看到用法（完整命令详解见本专栏命令篇）。

五、固定版本安装方案（B：按提交 SHA 锁定）

方案 B 与 A 的唯一区别是下载 URL 用完整提交 SHA 替换 master，保证任何时候拿到同一份代码。

5.1 按 SHA 下载

$ cd /root
$ curl -o maza https://raw.githubusercontent.com/tanrax/maza-ad-blocking/313491eea917009699976aeccc7db18235001e4d/maza
$ sha256sum maza
bdfb8fda1c5523cf5ffa227f5efbda63fef3360abc39b299b8c7061ad486b41a  maza

哈希与方案 A 实测值完全一致，证明两份下载内容相同。

5.2 校验脚本内嵌的版本特征

固定版本后可抽查脚本头部的默认规则源变量，确认是预期快照：

$ head -8 /root/maza | tail -2
URL_DNS_LIST="https://pgl.yoyo.org/adservers/serverlist.php?showintro=0&mimetype=plaintext"
URL_DNS_LIST_CUSTOM=""

随后同样执行 4.3 的 chmod +x + mv 完成安装。

5.3 离线 / 内网分发

完全离线的服务器：在任意一台能联网的机器按 5.1 下载并校验哈希，然后把这 6 KB 的脚本经跳板机、内网文件共享或 U 盘拷到目标机的 /usr/local/bin/maza 并 chmod +x 即可。注意离线只影响安装分发，maza update 仍需下载规则清单——内网场景可把清单换成内网地址（自定义规则源写法见本专栏配置篇）。

六、方案对比与选择建议

选择建议：个人笔记本图省事用方案 A；任何要写进文档/剧本（playbook）的安装都用方案 B，并把 SHA-256 一并记录。两者安装后的使用方式完全相同。

七、启用与首次验证（hosts 模式）

安装后默认未启用，本节完成首次启用并逐项验证。

7.1 启用前状态

$ maza status
DISABLED
$ wc -l /etc/hosts
7 /etc/hosts
$ grep -c '^127.0.0.1 ' /etc/hosts
0

7.2 一键启用

maza start 内部先执行一次 update（下载并清洗规则清单、写入 hosts 与 dnsmasq 规则文件），再输出启用提示：

$ time maza start
List updated!
ENABLED!

real	0m1.414s
user	0m0.062s
sys	0m0.045s

整个过程约 1.4 秒（取决于规则源下载速度）。再次查看状态与 hosts 变化：

$ maza status
ENABLED
$ wc -l /etc/hosts
3572 /etc/hosts
$ grep -c '^127.0.0.1 ' /etc/hosts
3561

/etc/hosts 从 7 行变为 3572 行：新增 3 行段头注释 + 3561 条屏蔽记录 + 1 行结束标记。屏蔽段首尾形态：

$ sed -n '8,12p' /etc/hosts
## MAZA - List ad blocking
### https://github.com/tanrax/maza-ad-blocking
### Created by Andros Fenollosa (https://andros.dev/)
127.0.0.1 101com.com
127.0.0.1 180hits.de
$ tail -2 /etc/hosts
127.0.0.1 zzhc.vnet.cn
## END MAZA

同时生成两个规则文件（供第九章与 dnsmasq 集成使用）：

$ ls -l /root/.config/maza/
total 188
-rw-r--r-- 1 root root      0 Oct 25 16:09 custom-domains
-rw-r--r-- 1 root root 126763 Oct 25 16:10 dnsmasq.conf
-rw-r--r-- 1 root root    157 Oct 25 16:09 ignore
-rw-r--r-- 1 root root  59104 Oct 25 16:10 list

7.3 验证拦截生效

用 getent 走系统解析器验证：屏蔽域名被解析到本机，正常域名不受影响：

$ getent hosts googleadservices.com
127.0.0.1       googleadservices.com
$ getent hosts example.com
2606:4700:10::6814:179a example.com
2606:4700:10::ac42:93f3 example.com

模拟浏览器访问被拦域名，连接立即被拒绝（本机 80 端口无服务）：

$ curl googleadservices.com
curl: (7) Failed to connect to googleadservices.com port 80 after 0 ms: Connection refused
$ echo $?
7

这正是官方 README 描述的命中现象——广告请求在解析层被指向 127.0.0.1，根本到不了广告服务器。

7.4 hosts 模式边界：子域名不拦截

hosts 是字面精确匹配，清单里只列了主域时，子域名直接漏过：

$ getent hosts sub.googleadservices.com
$ echo $?
2

子域名查不到任何记录（getent 退出码 2），说明没有被拦截。需要通配子域拦截时进入第八章启用 dnsmasq 模式。

💡 技术拓展：「通配拦截」在 DNS 层有三种常见形态——

形态	匹配能力	代表
hosts 静态映射	仅字面精确匹配	/etc/hosts（Maza hosts 模式）
域后缀通配	example.com 命中全部子域	dnsmasq address=/域/IP（Maza dnsmasq 模式）
正则/语法规则	`

本文采用第二种：不重写规则清单，只把解析层换成支持域后缀通配的 dnsmasq。

八、可选：集成 dnsmasq（通配子域 + 局域网拦截）

Maza 每次 update 都会同步生成 ~/.config/maza/dnsmasq.conf（3565 行 address=/域名/127.0.0.1 规则），但不会替你安装或配置 dnsmasq。本章完成挂载与验证。

8.1 安装 dnsmasq

$ apt-get update -qq
$ apt-get install -y dnsmasq
Need to get 20.5 kB of archives.
After this operation, 98.3 kB of additional disk space will be used.
Get:1 http://archive.ubuntu.com/ubuntu jammy-updates/universe amd64 dnsmasq all 2.91-0ubuntu0.22.04.2 [20.5 kB]
...
Setting up dnsmasq (2.91-0ubuntu0.22.04.2) ...
Created symlink /etc/systemd/system/multi-user.target.wants/dnsmasq.service → /lib/systemd/system/dnsmasq.service.
（输出节选，实测首尾）

启动并确认服务状态：

$ systemctl start dnsmasq
$ systemctl is-active dnsmasq
active
$ systemctl is-enabled dnsmasq
enabled
$ dnsmasq --version | head -1
Dnsmasq version 2.91  Copyright (c) 2000-2025 Simon Kelley

8.2 挂载 Maza 规则文件

把 Maza 生成的规则文件追加进 /etc/dnsmasq.conf（追加一行即可，conf-file= 指令让 dnsmasq 额外加载该文件）：

$ echo 'conf-file=/root/.config/maza/dnsmasq.conf' >> /etc/dnsmasq.conf
$ grep -n 'conf-file' /etc/dnsmasq.conf | tail -1
692:conf-file=/root/.config/maza/dnsmasq.conf
$ systemctl restart dnsmasq
$ systemctl is-active dnsmasq
active

确认 53 端口已在监听（UDP）：

$ ss -ulnp | grep :53
UNCONN 0      0            0.0.0.0:53         0.0.0.0:*    users:(("dnsmasq",pid=4160,fd=4))
UNCONN 0      0               [::]:53            [::]:*    users:(("dnsmasq",pid=4160,fd=6))

⚠️ 注意：改的是 /etc/dnsmasq.conf 主配置。若你更倾向 /etc/dnsmasq.d/ 目录，也可以在里面放一个软链接指向 Maza 规则文件，效果相同。

8.3 通配拦截验证

dnsmasq 模式下，主域与任意层级子域都被拦截，正常域名转发上游不受影响：

$ dig @127.0.0.1 googleadservices.com +short
127.0.0.1
$ dig @127.0.0.1 sub.googleadservices.com +short
127.0.0.1
$ dig @127.0.0.1 example.org +short
172.66.157.237
104.20.26.136

对比 7.4：子域名 sub.googleadservices.com 在 hosts 模式漏拦，在 dnsmasq 模式被应答 127.0.0.1。

如需观察拦截日志，在 /etc/dnsmasq.conf 追加 log-queries 与 log-facility=/var/log/dnsmasq.log 并重启，日志中可看到命中记录（输出节选）：

Oct 25 14:58:09 dnsmasq[4201]: query[A] pagead2.googlesyndication.com from 127.0.0.1
Oct 25 14:58:09 dnsmasq[4201]: config pagead2.googlesyndication.com is 127.0.0.1

日志中的 config 应答（相对的是 forwarded 转发上游）表示该查询被本地配置——即 Maza 规则——直接应答为 127.0.0.1，未转发上游。

8.4 局域网客户端接入

同网段客户端只需把 DNS 指向服务器 A（10.89.56.4）。客户端 B 的 /etc/resolv.conf：

$ cat /etc/resolv.conf
nameserver 10.89.56.4
options edns0

客户端实测：屏蔽域（含子域）应答 127.0.0.1，正常域返回真实 IP——客户端自身不需要安装任何东西：

$ dig googleadservices.com +short
127.0.0.1
$ dig pagead2.googlesyndication.com +short
127.0.0.1
$ dig example.org +short
172.66.157.237
104.20.26.136

这就是"Like Pi-hole but local"的完整形态：一台服务器跑 dnsmasq，整个局域网去广告。

8.5 关键陷阱：start/stop 不重载 dnsmasq

Maza 的 start/stop 只改写规则文件与 hosts，不会重载 dnsmasq；运行中的 dnsmasq 进程继续使用启动时读入的规则。实测对照（dig @127.0.0.1 googleadservices.com +short 的结果）：

⚠️ 注意：凡执行 maza start / maza stop / maza update，若已挂载 dnsmasq 规则，必须紧跟 systemctl restart dnsmasq，否则 dnsmasq 层看到的是旧规则。hosts 层无此问题（每次解析都读文件）。

九、配置说明

9.1 配置目录与四个文件

Maza 遵循 XDG_CONFIG_HOME，默认配置目录为 ~/.config/maza/（root 即 /root/.config/maza/），四个文件均为纯文本：

list 与 dnsmasq.conf 是每次 update 重新生成的产物，手工改动会被覆盖；要持久影响规则就改 ignore 与 custom-domains（写法与陷阱见本专栏配置篇）。

9.2 hosts 屏蔽段结构

/etc/hosts 中的屏蔽段被一对标记包裹，update/stop 都靠它定位：

## MAZA - List ad blocking        ← 起始标记（status 据此判断 ENABLED）
### https://github.com/tanrax/maza-ad-blocking
### Created by Andros Fenollosa (https://andros.dev/)
127.0.0.1 101com.com
…（3561 条）…
127.0.0.1 zzhc.vnet.cn
## END MAZA                        ← 结束标记

重复执行 update 会先整段删除再写入，幂等无累积。

9.3 定时自动更新

规则清单会持续演进，官方建议用 cron 每日更新。Ubuntu 22.04 默认带 cron（最小化安装若无，apt-get install -y cron）：

$ crontab -e   # 写入下行（生产频率）
@daily /usr/local/bin/maza update > /root/cron-maza.log 2>&1

实测为快速验证把频率临时调成每分钟，crontab -l 与一分钟后的日志：

$ crontab -l
*/1 * * * * /usr/local/bin/maza update > /root/cron-maza.log 2>&1
$ cat /root/cron-maza.log
List updated!

日志出现 List updated! 即定时更新链路可用，随后把频率改回 @daily。

⚠️ 注意：cron 以非交互 shell 执行，maza 必须写绝对路径 /usr/local/bin/maza；若挂了 dnsmasq，更新后同样要重启 dnsmasq 才生效（可在 crontab 再加一行 @daily systemctl restart dnsmasq）。

十、常见问题（FAQ）

Q1：下载脚本时 curl 报 exit 56 / http_code=000？ 实测当日 raw.githubusercontent.com 直连偶发连接重置，直接重试即可（实测最多重试 3 次成功）。可加重试参数：curl --retry 3 -o maza <URL>。持续失败检查本机代理与出口防火墙。

Q2：maza update 执行到一半失败，会怎样？ 实测把规则源置为不可达后执行 update：curl 退出码 7，脚本因 set -e 立即中断。此时 /etc/hosts 的旧屏蔽段原样保留（maza status 仍 ENABLED，3561 条仍在），但配置目录里的 list/dnsmasq.conf 已在下载前被删除（目录只剩 custom-domains 与 ignore）。恢复方法：网络恢复后重新执行 maza update，清单与 dnsmasq 规则会重建（实测恢复后 dig 应答回到 127.0.0.1）。

Q3：maza stop 后 dnsmasq 还在拦截？ 正常现象：stop 只清空规则文件，不重载 dnsmasq。补一条 systemctl restart dnsmasq 即解除（实测对照见 8.5）。

Q4：为什么 sub.googleadservices.com 这类子域名没拦住？ hosts 模式只精确匹配清单字面域名。挂 dnsmasq 用 address=/域/127.0.0.1 规则即可通配全部子域（见第八章）。

Q5：crontab: command not found？ 最小化安装的 Ubuntu 未装 cron，apt-get install -y cron 后即可（桌面/服务器版默认自带）。

Q6：规则里好多误杀，想放行几个域名？ 写入 ~/.config/maza/ignore 后重新 maza update。注意它是子串匹配删除，写 ads 会删掉所有含 ads 的域名（实测清单从 3564 条骤减到 3017 条），务必写完整域名；细讲见本专栏配置篇。

十一、卸载与清理

Maza 无常驻进程，卸载 = 关拦截 + 删脚本 + 删配置目录，全程实测如下。

11.1 关闭拦截

$ maza stop
DISABLED!
$ maza status
DISABLED
$ wc -l /etc/hosts
7 /etc/hosts
$ getent ahosts googleadservices.com
114.250.63.38   STREAM googleadservices.com
114.250.63.38   DGRAM

stop 把屏蔽段从 /etc/hosts 整段移除，域名恢复真实解析。

11.2 删除程序与配置

$ rm -f /usr/local/bin/maza
$ rm -rf /root/.config/maza
$ echo $?
0

11.3 处理 dnsmasq（如挂载过）

只想解除拦截：删掉 /etc/dnsmasq.conf 里那行 conf-file= 后 systemctl restart dnsmasq。彻底移除 dnsmasq：

$ apt-get remove --purge -y dnsmasq
...
Purging configuration files for dnsmasq (2.91-0ubuntu0.22.04.2) ...
（输出节选，实测首尾）
$ systemctl is-active dnsmasq
inactive
$ ss -ulnp | grep :53
（无输出，53 端口已无监听）

11.4 卸载后复核

$ maza status
bash: maza: command not found
$ echo $?
127
$ ls /root/.config/maza
ls: cannot access '/root/.config/maza': No such file or directory
$ wc -l /etc/hosts
7 /etc/hosts

命令消失（exit 127）、配置目录不存在、hosts 回到 7 行——卸载干净。若之前做过 /etc/hosts.backup，确认无残留问题后可自行删除或留档。

十二、参考链接