Maza 2026.08 配置参数详解

目标：把 Maza 2026.08（master 提交 313491e）的全部可调项讲透——脚本内嵌变量、配置目录四个文件（list/dnsmasq.conf/ignore/custom-domains）、自定义规则源与 dnsmasq 侧配置，逐项给默认值、改法与实测回显，并沉淀白名单子串误删、脏数据透传、规则源中断等排障实录。全部命令已在 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 快照 = master 提交 313491eea917009699976aeccc7db18235001e4d，脚本 233 行 / 5986 字节，SHA-256 bdfb8fda1c5523cf5ffa227f5efbda63fef3360abc39b299b8c7061ad486b41a
• 运行依赖：bash 5.1.16、curl 7.81.0、GNU sed；可选 dnsmasq 2.91
• 默认配置目录：/root/.config/maza/（root 下 $HOME/.config/maza/）
• 实测日期：2026-10-25

二、前置条件

1. 已按安装篇完成安装并能正常执行 maza status（输出 ENABLED 或 DISABLED 均可）。
2. 改任何配置后，必须重新执行 maza update 才会生效——list、dnsmasq.conf、/etc/hosts 屏蔽段都是 update 时重新生成的产物，手工改产物文件会被下次 update 覆盖。
3. 若已把 dnsmasq.conf 挂进 dnsmasq，update 后还要 systemctl restart dnsmasq（原因与实测对照见安装篇 8.5 节）。

三、参数体系与修改方式

Maza 没有独立配置文件格式，全部可调项分三层，修改方式各不相同：

脚本变量实测清单（grep -n 自 2026.08 快照，行号即真实行号）：

7:URL_DNS_LIST="https://pgl.yoyo.org/adservers/serverlist.php?showintro=0&mimetype=plaintext"
8:URL_DNS_LIST_CUSTOM=""
13:HOST_FILE=/etc/hosts
23:LIST="list"
24:LIST_DNSMASQ="dnsmasq.conf"
25:CUSTOM_DOMAINS="custom-domains"
38:IGNORE_LIST_FILE="ignore"
39:START_TAG="## MAZA - List ad blocking"
40:PROJECT="### https://github.com/tanrax/maza-ad-blocking"
41:AUTHOR="### Created by Andros Fenollosa (https://andros.dev/)"
42:END_TAG="## END MAZA"

⚠️ 注意：直接改 /usr/local/bin/maza 意味着"升级脚本即丢配置"。固定版本（按 SHA 安装）的场景下这不是问题，但要记得改完重新记录哈希——改过的脚本 SHA-256 不再是 bdfb8fda…b41a。

四、脚本变量参数详解

4.1 规则源：URL_DNS_LIST 与 URL_DNS_LIST_CUSTOM

update 的取源逻辑（脚本原文）：URL_DNS_LIST_CUSTOM 非空则打印一行 si（西班牙语"是"，上游遗留的调试输出）并改用自定义源，否则用默认源。自定义源的完整实测见第八章。

4.2 路径与文件名变量

后四个只是文件名常量，正常无需改；真正常改的路径是配置目录本身（由 XDG_CONFIG_HOME 决定，见第五章）。

4.3 标记变量（status/stop 的定位锚）

START_TAG / END_TAG（第 39/42 行）是 /etc/hosts 屏蔽段的起止标记，status 靠 grep -qF "$START_TAG" 判断启用与否，stop/update 靠 sed "/$START_TAG/,/$END_TAG/d" 整段删除。PROJECT/AUTHOR 是写入段首的两行注释。不要改这四个变量：改了 START_TAG 后旧段将永远无法被识别清理。

4.4 系统检测变量

NAME_OSX="Darwin" 与 THIS_OS=$(uname -mrs) 用于 macOS 判定：命中 Darwin 时 sed 换成 gsed（未装会直接报错退出）。Linux 下无感知，无需配置。

五、配置目录与 XDG_CONFIG_HOME

5.1 默认目录与四个文件

脚本第 12 行：XDG_CONFIG_HOME 为空时 CONFIG=$HOME/.config/maza/，否则 CONFIG=$XDG_CONFIG_HOME/maza/。root 默认即 /root/.config/maza/，实测内容：

$ 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

5.2 用 XDG_CONFIG_HOME 迁移配置目录（实测）

把配置目录迁到独立分区（如 /opt/maza-conf）：

$ export XDG_CONFIG_HOME=/opt/maza-conf
$ maza update
List updated!
$ ls -l /opt/maza-conf/maza/
total 196
drwxr-xr-x 2 root root 4096 Oct 25 15:00 .
drwxr-xr-x 3 root root 4096 Oct 25 15:00 ..
-rw-r--r-- 1 root root      0 Oct 25 15:00 custom-domains
-rw-r--r-- 1 root root 126763 Oct 25 15:00 dnsmasq.conf
-rw-r--r-- 1 root root    157 Oct 25 15:00 ignore
-rw-r--r-- 1 root root  59104 Oct 25 15:00 list
$ wc -l /opt/maza-conf/maza/list
3565 /opt/maza-conf/maza/list

新目录自动创建并生成全套文件。注意环境变量只对当前会话生效，长期使用要写进 /etc/profile.d/maza.sh 或 root 的 ~/.bashrc；cron 任务里同样要带 XDG_CONFIG_HOME=/opt/maza-conf 前缀，否则定时任务会读写默认目录。

六、白名单 ignore

6.1 默认值与工作机制

ignore 不存在时，update 自动写入 12 条默认项（保护本机解析不被屏蔽）：

$ cat /root/.config/maza/ignore
localhost
localhost.localdomain
local
broadcasthost
ip6-localhost
ip6-loopback
ip6-localnet
ip6-mcastprefix
ip6-allnodes
ip6-allrouters
ip6-allhosts
0.0.0.0

工作机制（脚本原文）：逐行读 ignore，对 list 执行 sed -i.bak "/$line/d"——凡是包含该字符串的行整行删除。放行一个域名的标准做法：

$ echo 'doubleclick.net' >> /root/.config/maza/ignore
$ maza update
List updated!

实测放行后清单剩 3564 条（doubleclick.net 及其含该串的行被移除）。

6.2 子串匹配陷阱（实测排障）

ignore 不是"域名精确匹配"，是子串匹配。往 ignore 写入 ads 这种短串的实测后果：

$ wc -l < /root/.config/maza/list   # 基线
3564
$ echo 'ads' >> /root/.config/maza/ignore
$ maza update
List updated!
$ wc -l < /root/.config/maza/list   # 加入 ads 后
3017
$ grep -c 'ads' /root/.config/maza/list
0

547 条规则被一并误删——凡域名中含 ads 字串的全部遭殃。而 518ad.com（含 ad 不含 ads）幸存，仍出现在清单头部附近：

## MAZA - List ad blocking
### https://github.com/tanrax/maza-ad-blocking
518ad.com

⚠️ 注意：ignore 只写完整域名，绝不写短词。误删后把短词从 ignore 移除再 maza update 即可恢复。

6.3 ignore 对 custom-domains 无效

脚本流程决定：先按 ignore 删清单，之后才追加 custom-domains。把 maza-custom.example 同时写进 ignore 和 custom-domains 的实测：

$ maza update
List updated!
$ grep -c 'maza-custom.example' /root/.config/maza/list
1

自定义域名依旧进清单。想撤回自定义屏蔽，只能从 custom-domains 里删行。

七、自定义屏蔽 custom-domains

7.1 追加机制与实测

custom-domains 每行一项，update 时原样追加到清洗后清单末尾，随后一同写进 hosts 与 dnsmasq 规则：

$ printf 'maza-custom.example\n' >> /root/.config/maza/custom-domains
$ maza update
List updated!
$ grep -n 'maza-custom' /root/.config/maza/list
3565:maza-custom.example
$ grep -n 'maza-custom' /etc/hosts
3572:127.0.0.1 maza-custom.example

清单 3565 行、hosts 3572 行均出现，拦截即刻生效。

7.2 脏数据原样透传（实测）

Maza 不校验 custom-domains 的格式。误把 URL 写进去：

$ printf 'https://maza-url.example/\n' >> /root/.config/maza/custom-domains
$ maza update
List updated!
$ grep -n 'maza-url' /root/.config/maza/list
3566:https://maza-url.example/
$ grep -n 'maza-url' /etc/hosts
3573:127.0.0.1 https://maza-url.example/

127.0.0.1 https://maza-url.example/ 这种垃圾行进了 hosts 也不会被任何查询命中，纯属无效占位；更糟的是若写成带空格的串会破坏 hosts 行格式。

⚠️ 注意：custom-domains 只接受纯域名（字母、数字、点、连字符），写入前自行检查，写错不会让 update 报错。

7.3 hosts 与 dnsmasq 产物差异：连字符规整

脚本只对 dnsmasq.conf 做连字符折叠（---→-、--→-），list 与 hosts 保持原样。实测写入 maza---hyphen.example：

$ grep -n 'hyphen' /root/.config/maza/list
3567:maza---hyphen.example
$ grep -n 'hyphen' /root/.config/maza/dnsmasq.conf
3567:address=/maza-hyphen.example/127.0.0.1

同一域名在两份产物里不一致：dnsmasq 拦的是 maza-hyphen.example，hosts 拦的是 maza---hyphen.example。结论：自定义域名避免使用连续连字符，否则两种模式的拦截对象会悄悄分叉。

八、自定义规则源 URL_DNS_LIST_CUSTOM

8.1 设置方法与 file:// 实测

编辑脚本第 8 行，指向任意 hosts/纯域名格式清单 URL。curl 支持 file://，用本地清单做完整实测：

$ sed -n '8p' /usr/local/bin/maza
URL_DNS_LIST_CUSTOM="file:///root/maza-custom-list.txt"
$ maza update
si
List updated!

输出多出的 si 即 4.1 所述的调试打印，代表"已切换自定义源"。实测清单内容（本地文件 3 个域 + custom-domains 4 项追加）：

$ cat /root/.config/maza/list
## MAZA - List ad blocking
### https://github.com/tanrax/maza-ad-blocking
### Created by Andros Fenollosa (https://andros.dev/)
site-z.example
site-y.example
site-w.example
beauty-tea.com
maza-custom.example
https://maza-url.example/
maza---hyphen.example
## END MAZA
$ grep -n 'site-z' /etc/hosts
11:127.0.0.1 site-z.example

默认源被完全替换（不再是 3561 条），hosts 第 11 行起就是自定义源的域名。改回默认：把第 8 行恢复为空字符串再 update：

$ sed -n '8p' /usr/local/bin/maza
URL_DNS_LIST_CUSTOM=""
$ maza update
List updated!
$ grep -c '^127.0.0.1 ' /etc/hosts
3561

💡 技术拓展：广告规则清单有三种主流格式，选源时先认清格式——

格式	形态	代表源	Maza 兼容性
纯域名清单	每行一个域名	pgl.yoyo.org（默认源）	直接支持
hosts 格式	0.0.0.0 域名	StevenBlack/hosts	支持（update 自动剥前缀）
AdBlock 语法	||域名^、##.ad-banner	EasyList	不支持（不会解析修饰符）

本文实测用纯域名清单；换第三方源时优先选前两类。

8.2 规则源不可达时的行为与恢复（排障实录）

把自定义源指向不可达地址后执行 update，完整现场：

$ 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
$ grep -c '^127.0.0.1 ' /etc/hosts
3561
$ maza status
ENABLED

三点结论：

1. curl 失败（exit 7）+ set -e → 脚本立即中断，无部分写入；
2. list/dnsmasq.conf 已在下载前被 rm -f 删除 → 配置目录只剩 ignore 与 custom-domains；
3. /etc/hosts 旧屏蔽段原样保留 → 拦截不中断，仍 ENABLED、3561 条在位。

恢复只需源可达后重跑：

$ maza update
List updated!
$ grep -c '^127.0.0.1 ' /etc/hosts
3561
$ dig @127.0.0.1 googleadservices.com +short
127.0.0.1

⚠️ 注意：挂了 dnsmasq 的场景，update 失败期间 dnsmasq.conf 已消失，若此时重启 dnsmasq 会导致其规则整体丢失——排障期间不要重启 dnsmasq。

九、dnsmasq 侧配置

Maza 只负责生成 dnsmasq.conf 规则文件，dnsmasq 自身的三项关键配置：

挂载与验证的完整命令、回显及"update/stop 后必须重启 dnsmasq"的实测对照，见 《Ubuntu 22.04 安装 Maza 2026.08 指南》第八章；日志实测：

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 开头的应答行即命中 Maza 规则的记录（正常域则显示 forwarded 转发上游 + reply 真实 IP）。

十、生产配置模板

10.1 单机 hosts 模式（开发机/笔记本，1~2 GB 内存即可）

# 1. 脚本变量保持默认（仅确认第 8 行为空）
sed -n '8p' /usr/local/bin/maza     # 期望 URL_DNS_LIST_CUSTOM=""
# 2. 白名单：只写完整域名
echo 'doubleclick.net' >> /root/.config/maza/ignore
# 3. 自定义屏蔽：纯域名
echo 'maza-custom.example' >> /root/.config/maza/custom-domains
# 4. 生效
maza update
# 5. 定时更新（cron）
crontab -e    # @daily /usr/local/bin/maza update > /root/cron-maza.log 2>&1

10.2 网关 dnsmasq 模式（家庭/小团队网关，树莓派 4 GB 级）

在 10.1 基础上追加：

# 6. 挂载规则 + 日志
echo 'conf-file=/root/.config/maza/dnsmasq.conf' >> /etc/dnsmasq.conf
echo 'log-queries' >> /etc/dnsmasq.conf
echo 'log-facility=/var/log/dnsmasq.log' >> /etc/dnsmasq.conf
systemctl restart dnsmasq
# 7. 定时更新后自动重载（关键）
crontab -e    # @daily /usr/local/bin/maza update > /root/cron-maza.log 2>&1 && systemctl restart dnsmasq
# 8. 局域网设备 DNS 指向本机即可，无需逐台装 Maza

两套模板的共同纪律：ignore/custom-domains 改动一律以 maza update 收尾；dnsmasq 模式一律以 systemctl restart dnsmasq 收尾。

十一、常见问题（FAQ）

Q1：往 ignore 加了域名，hosts 里还有？ 两个高频原因：没重新 maza update（配置只在 update 时生效）；或该域名是被 custom-domains 追加的——ignore 管不到它（见 6.3），要从 custom-domains 删行。

Q2：ignore 能写通配符吗，比如 *.ads.com？ 不能。ignore 是 sed 子串删除（6.2），* 不会按通配理解；且 hosts 模式本身不支持通配子域。要整域放行/屏蔽，写主域名或改用 dnsmasq 模式。

Q3：custom-domains 里写了 https:// 开头的条目会怎样？ 原样透传进清单与 hosts，生成 127.0.0.1 https://maza-url.example/ 这类垃圾行（实测见 7.2），不报错也不生效。只写纯域名。

Q4：换了自定义规则源，想换回默认的？ 把脚本第 8 行 URL_DNS_LIST_CUSTOM 恢复为空字符串，再 maza update，实测回到 3561 条默认清单（见 8.1）。

Q5：update 中途失败，hosts 会被清空吗？ 不会。实测 curl 失败（exit 7）时 hosts 旧段原样保留、仍 ENABLED；但 list/dnsmasq.conf 会被删除，源恢复后重跑 update 重建（见 8.2）。

Q6：能不能只屏蔽、不污染 hosts，纯用 dnsmasq？ 不能。update 无条件同时写 hosts 与 dnsmasq.conf 两份产物；hosts 屏蔽段只能靠 maza stop 移除，而 stop 同时会清空 dnsmasq.conf。两者在脚本里是绑定的。

十二、参考链接