Maza 2026.08 常用 CLI 命令详解

目标：逐一实测 Maza 2026.08（master 提交 313491e）的全部 CLI 子命令——status/update/start/stop/--help，含参数解析行为、退出码、产物清单、失败现场与恢复，以及配套的 getent/curl/dig 验证命令组合与 cron 定时更新。全部回显在 Ubuntu 22.04.5 LTS 逐行照抄。安装见《Ubuntu 22.04 安装 Maza 2026.08 指南》，配置项见《Maza 2026.08 配置参数详解》。

一、环境信息

操作系统：Ubuntu 22.04.5 LTS（x86_64），root 账号
软件基线：Maza 2026.08 快照（313491eea917009699976aeccc7db18235001e4d），单文件 Bash 脚本 233 行，安装于 /usr/local/bin/maza
辅助命令：getent（libc 自带）、curl 7.81.0、dig 9.18.39（bind9-dnsutils）、cron 3.0pl1
可选服务：dnsmasq 2.91（第十章资源占用与 dnsmasq 层验证用）
实测日期：2026-10-25

二、工具概览

Maza 只有一个可执行文件 maza，共 5 个入口（4 个子命令 + --help），无任何参数旗标：

入口	作用	是否联网	影响面
`maza status`	查询拦截是否启用	否	只读
`maza update`	下载规则源并重建 hosts 段与 dnsmasq 规则	是	读写 hosts 与配置目录
`maza start`	= update + 启用提示	是	同上
`maza stop`	移除 hosts 屏蔽段、清空 dnsmasq 规则	否	读写 hosts 与配置目录
`maza --help`	打印用法	否	只读（但退出码为 1，见 4.1）

配套验证不依赖 Maza 自身：hosts 层用 getent/curl，dnsmasq 层用 dig，定时更新用 crontab，第九章起逐一给出。

三、前置条件

已安装 maza 到 /usr/local/bin 且以 root 执行（需改写 /etc/hosts）。
update/start 需要能下载规则源（默认 pgl.yoyo.org）；离线环境先按配置篇第八章换内网源。
已挂 dnsmasq 的场景，任何 start/stop/update 之后都要补 systemctl restart dnsmasq（实测依据见 8.2）。

四、maza --help 与参数解析行为

4.1 --help 实测（退出码是 1）

$ maza --help
Usage: maza [OPTION]
Simple and efficient local ad blocking throughout the network.

Options:
status       Check if it's active or not
update       Update the list of DNS to be blocked
start        Activate blocking DNS.
stop         Stop blocking DNS.
--help       Display this usage message and exit
$ echo $?
1

⚠️ 注意：--help 正常打印用法但退出码为 1（脚本 usage() 固定 exit 1）。在 Ansible/CI 里用 maza --help 探活会误判失败，探活请改用 maza status。

4.2 无参数与未知参数

$ maza
Error: Not enough arguments
Usage: maza [OPTION]
Simple and efficient local ad blocking throughout the network.

Options:
status       Check if it's active or not
update       Update the list of DNS to be blocked
start        Activate blocking DNS.
stop         Stop blocking DNS.
--help       Display this usage message and exit
$ echo $?
1
$ maza foo
Error: Not enough arguments
Usage: maza [OPTION]
Simple and efficient local ad blocking throughout the network.

Options:
status       Check if it's active or not
update       Update the list of DNS to be blocked
start        Activate blocking DNS.
stop         Stop blocking DNS.
--help       Display this usage message and exit
$ echo $?
1

未知参数（如 foo、不存在的 --version）不会被点名报错——脚本的 case *) 分支什么都不做，最终因"没有任何子命令被执行"而落入 Not enough arguments。排障时别被这句误导，先检查拼写。

五、maza status — 状态查询

5.1 用法与回显

$ maza status
ENABLED
$ maza stop
DISABLED!
$ maza status
DISABLED

输出只有两种：ENABLED（启用中，绿色）/ DISABLED（未启用，红色；非终端环境下无颜色码）。

5.2 判定原理与退出码

判定逻辑是 grep -qF "## MAZA - List ad blocking" /etc/hosts——只看 hosts 里有没有起始标记，与 dnsmasq 无关。实测退出码：

$ maza status
ENABLED
$ echo $?
0
$ maza stop && maza status
DISABLED!
DISABLED
$ echo $?
0

ENABLED 与 DISABLED 退出码都是 0（echo 收尾所致）。脚本化判断必须解析输出文本，例如：

[ "$(maza status)" = "ENABLED" ] && echo on || echo off

六、maza update — 规则更新

6.1 用法与回显

$ time maza update
List updated!

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

一次更新约 1.4 秒（取决于规则源下载）。背后依次做：选源（自定义源非空时先打印一行 si）→ 删除旧产物 → curl 下载 → sed 清洗（去注释/行尾空格/0.0.0.0、127.0.0.1 前缀）→ 应用 ignore 白名单 → 追加 custom-domains → 重写 hosts 屏蔽段 → 生成 dnsmasq.conf。

6.2 产物清单

$ 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
$ wc -l /etc/hosts
3572 /etc/hosts
$ grep -c '^127.0.0.1 ' /etc/hosts
3561

hosts 屏蔽段以 ## MAZA - List ad blocking 开头、## END MAZA 收尾，重复执行幂等覆盖、不累积。各文件格式与改法见配置篇，这里只需记住：list/dnsmasq.conf/hosts 段都是产物，别手工改。

6.3 失败现场与恢复

规则源不可达时实测：

$ maza update
si
$ echo $?
7
$ ls -l /root/.config/maza/
total 4
-rw-r--r-- 1 root root   0 Oct 25 15:01 custom-domains
-rw-r--r-- 1 root root 157 Oct 25 15:01 ignore
$ maza status
ENABLED

curl 失败（exit 7）+ set -e 使脚本中断：list/dnsmasq.conf 已在下载前被删，但 hosts 旧段原样保留、拦截不中断。源恢复后重跑 maza update 即可重建（完整排障记录见配置篇 8.2）。

七、maza start — 启用拦截

start 就是 update 加一行启用提示，首次启用与停用后再启用都用它：

$ maza start
List updated!
ENABLED!
$ echo $?
0
$ maza status
ENABLED

启用后立即按第九章验证。已挂 dnsmasq 时补 systemctl restart dnsmasq。

八、maza stop — 停用拦截

8.1 用法与回显

$ maza stop
DISABLED!
$ echo $?
0
$ maza status
DISABLED
$ wc -l /etc/hosts
7 /etc/hosts

stop 做两件事：从 /etc/hosts 删除整个屏蔽段（3572 行回落到 7 行）、把 dnsmasq.conf 清空为 0 字节。hosts 层拦截即刻解除：

$ getent ahosts googleadservices.com
114.250.63.38   STREAM googleadservices.com
114.250.63.38   DGRAM

8.2 dnsmasq 重载陷阱（实测对照）

stop（以及 start/update）不重载 dnsmasq，运行中的进程仍按启动时读入的规则应答。实测对照（dig @127.0.0.1 googleadservices.com +short）：

步骤	操作	dig 结果
A	`maza stop`，不重启 dnsmasq	127.0.0.1（仍在拦截！）
B	`systemctl restart dnsmasq`	114.250.70.38（真实 IP，解除）
C	`maza start`，不重启 dnsmasq	114.250.70.38（未生效！）
D	`systemctl restart dnsmasq`	127.0.0.1（拦截恢复）

⚠️ 注意：dnsmasq 模式下，maza 子命令与 systemctl restart dnsmasq 必须成对执行，建议写进同一行 crontab（见 10.1）。

九、验证命令组合

9.1 hosts 层验证（任何模式可用）

$ getent hosts googleadservices.com        # 屏蔽域 → 127.0.0.1
127.0.0.1       googleadservices.com
$ getent hosts example.com                 # 正常域 → 真实地址
2606:4700:10::6814:179a example.com
2606:4700:10::ac42:93f3 example.com
$ curl googleadservices.com                # 模拟访问被拦域
curl: (7) Failed to connect to googleadservices.com port 80 after 0 ms: Connection refused
$ echo $?
7
$ getent hosts sub.googleadservices.com    # 子域名：hosts 模式漏拦
$ echo $?
2

9.2 dnsmasq 层与客户端验证

服务器本机（已挂 Maza 规则并重启 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

局域网客户端（/etc/resolv.conf 指向服务器 10.89.56.4，自身零安装）：

$ cat /etc/resolv.conf
nameserver 10.89.56.4
options edns0
$ dig googleadservices.com +short
127.0.0.1
$ dig example.org +short
172.66.157.237
104.20.26.136

dnsmasq 服务状态总览（systemctl status dnsmasq 节选，实测）：

● dnsmasq.service - dnsmasq - A lightweight DHCP and caching DNS server
     Loaded: loaded (/lib/systemd/system/dnsmasq.service; enabled; vendor preset: enabled)
     Active: active (running) since Sun 2026-10-25 15:09:20 UTC; 1min 24s ago

十、定时更新与资源占用

10.1 crontab 定时更新

官方推荐每日自动更新。生产写法：

@daily /usr/local/bin/maza update > /root/cron-maza.log 2>&1

实测为快速验证临时调成每分钟，链路验证如下：

$ 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 里必须写绝对路径 /usr/local/bin/maza；dnsmasq 模式把重载写进同一行：

@daily /usr/local/bin/maza update > /root/cron-maza.log 2>&1 && systemctl restart dnsmasq

⚠️ 注意：最小化安装的 Ubuntu 可能无 cron（crontab: command not found，exit 127），apt-get install -y cron 即可。

10.2 资源占用实测

Maza 自身是一次性脚本，无常驻进程、无端口；唯一的常驻开销来自可选的 dnsmasq：

$ ps -eo pid,rss,etime,cmd | grep [d]nsmasq
   4674  2892       01:52 /usr/sbin/dnsmasq -x /run/dnsmasq/dnsmasq.pid -u dnsmasq -7 /etc/dnsmasq.d,.dpkg-dist,.dpkg-old,.dpkg-new --local-service --trust-anchor=.,20326,8,2,E06D44B80B8F1D39A95C0B0D7C65D08458E880409BBC683457104237C7F8EC8D --trust-anchor=.,38696,8,2,683D2D0ACB8C9B712A1948B27F741219298D0A450D612C483AF444A4C0FB2B16

RSS 约 2.9 MB、挂载 3565 条规则后依然平稳——这也是 Maza 相对 Pi-hole/AdGuard Home 的核心卖点（量化对比见《Maza 2026.08 介绍与选型指南》第七章）。

十一、注意事项

退出码不可信：--help/无参数/未知参数恒 exit 1，status 恒 exit 0——自动化脚本一律解析输出文本，不要靠 $?。
start/stop/update 三件套都要联网吗：只有 update 与 start（内含 update）需要下载规则源；stop 与 status 纯本地操作。
dnsmasq 模式必须成对重启：任何会改规则的命令之后跟 systemctl restart dnsmasq，否则出现 8.2 的"状态与应答不一致"。
别手改产物：list、dnsmasq.conf、hosts 屏蔽段都是 update 产物，定制走 ignore 与 custom-domains（配置篇第六、七章）。
升级即重装：上游无版本号，"升级"=重新下载脚本覆盖 /usr/local/bin/maza；改过的脚本变量（如自定义源）会被重置，升级后需重设并 maza update。

十二、常见问题（FAQ）

Q1：maza --help 明明打印了帮助，为什么 CI 判失败？ --help 退出码恒为 1（4.1），CI 探活改用 maza status。

Q2：maza --version 怎么看版本？ 没有该参数，会落入"Not enough arguments"（4.2）。核对版本用 sha256sum /usr/local/bin/maza 对照安装篇第三章的基线哈希。

Q3：maza stop 后 maza status 仍 ENABLED？ status 只看 hosts 起始标记。stop 正常会删段；若仍 ENABLED，检查 /etc/hosts 是否可写、标记变量是否被改过。

Q4：update 后拦截没变化？ hosts 层看 grep -c '^127.0.0.1 ' /etc/hosts 是否为预期条数；dnsmasq 层先确认是否忘了 systemctl restart dnsmasq（8.2）。

Q5：能不能设别名简化验证？ 可以把 9.1 的三条封装进 shell 函数或 CI 步骤；Maza 自身不支持子命令别名。

十三、参考链接

来源	地址	用途
Maza 脚本源码（2026.08 快照）	https://raw.githubusercontent.com/tanrax/maza-ad-blocking/313491eea917009699976aeccc7db18235001e4d/maza	子命令与参数解析原文
Maza 官方仓库	https://github.com/tanrax/maza-ad-blocking	README（含 cron 建议）
安装与 dnsmasq 集成	《Ubuntu 22.04 安装 Maza 2026.08 指南》	0→1 安装与卸载
配置参数	《Maza 2026.08 配置参数详解》	变量/白名单/自定义源
定位与选型	《Maza 2026.08 介绍与选型指南》	架构与同类对比