Mailman 3.3.10 常用 CLI 命令详解
Mailman 3.3.10 Core 的 mailman 命令行工具 30 个子命令逐条实测详解：列表创建删除、成员增删改同步、owner/moderator 角色、摘要管理、队列排障三件套、MTA 别名生成、shell 交互与 systemd 混用排障实录。
Mailman邮件服务器邮件列表2026/10/21
Mailman 3.3.10 常用 CLI 命令详解
目标：把 GNU Mailman 3 Core 自带的
mailman命令行工具一次讲透——30 个子命令逐一给出参数表与真实运行回显，覆盖列表生命周期、成员与角色管理、摘要、队列排障、MTA 别名、Python 交互六大板块，并完整沉淀「systemd 托管与手工启停混用」的排障实录。已在 Ubuntu 22.04.5 LTS + Mailman 3.3.10 实测通过，全部输出为真实回显。
一、环境信息
本文所有命令与回显均在以下环境实测采集，读者在自己的服务器上应能得到一致的输出：
- 操作系统：Ubuntu 22.04.5 LTS（主机名
list.example.org） - Mailman Core：3.3.10（代号 Tom Sawyer），专用用户
mailman运行 - Python：3.10.12（系统自带版本）
- 配置文件：
/etc/mailman3/mailman.cfg（layout 为custom，数据根目录/opt/mailman/var） - 数据库：SQLite（
/opt/mailman/var/data/mailman.db） - REST API：
http://127.0.0.1:8001/3.1/，凭据restadmin:q1w2e3r4 - MTA：Postfix，经 LMTP（
127.0.0.1:8024）与 Core 对接 - 示例列表：
test@list.example.org、ops@list.example.org、cli-demo@list.example.org（本文实测过程中创建） - 安装方式：pip 虚拟环境（
/opt/mailman/venv），安装全流程见 《Ubuntu 22.04 安装 Mailman 指南》
💡 版本复查（2026-10-21）：PyPI 上
mailman包的最新稳定版仍为 3.3.10（2024-10-02 发布），3.3.11 尚处于 beta 阶段（社区用户环境中可见 3.3.11b1）。本文按 3.3.10 撰写，后续 3.3.11 正式发布后命令树预计无破坏性变化。
二、工具概览
2.1 mailman 命令与调用方式
Mailman 3 Core 的全部管理能力都收敛在一个 CLI 入口：/opt/mailman/venv/bin/mailman。它管理的是 Core 侧的对象（列表、成员、角色、队列），Postorius/HyperKitty 的 Web 功能不在本命令树内。
Core 拒绝以 root 身份运行，因此所有命令统一以专用用户执行，本文约定调用形式如下：
sudo -u mailman /opt/mailman/venv/bin/mailman <子命令> [参数]
命令较多时可以在管理员 shell 里定义一个别名减少敲击量（仅为便利，非必需）：
alias mm='sudo -u mailman /opt/mailman/venv/bin/mailman'
mm info
root 直接运行的拒绝行为实测（以 root 身份执行 mailman info）：
Usage: mailman [OPTIONS] [COMMAND] [ARGS]...
Try 'mailman --help' for help.
Error: If you are sure you want to run as root, specify --run-as-root.
即 Core 给了一条明路：确要以 root 执行需显式加 --run-as-root 全局选项（见 4.5 节），生产环境不推荐。
2.2 子命令总览（30 个）
mailman help 列出的命令树共 30 个子命令，按用途归类如下（mailman help 全量回显见 2.3 节）：
| 分类 | 子命令 | 用途 |
|---|---|---|
| 实例信息 | info、version | 实例配置摘要、路径与版本号 |
| 服务生命周期 | start、stop、restart、status、reopen | master 与 runner 进程的启停、状态、日志重开 |
| 列表生命周期 | create、remove、lists | 建列表、删列表、列出列表 |
| 成员与角色 | addmembers、delmembers、members、admins | 订阅/退订/查询成员，owner 与 moderator 管理 |
| 订阅同步与地址 | syncmembers、changeaddress、findmember | 成员名单整表同步、改地址、全局找成员 |
| 摘要 | digests | 立即发送摘要、卷号递增、dry-run |
| 队列与消息 | inject、qfile、unshunt、notify | 向队列投信、解析队列文件、处理 shunt 邮件、催办待审请求 |
| MTA 与配置 | aliases、conf | 生成 MTA 别名映射文件、打印配置键值 |
| 交互与迁移 | shell、withlist、import21、gatenews | Python 交互/脚本操作、从 Mailman 2.1 导入、NNTP 网关拉取 |
💡 说明：读者熟悉的「订阅/退订/邀请」在 Core CLI 中没有同名子命令——订阅入口是
addmembers（邀请订阅是它的-i/--invite选项），退订入口是delmembers；「归档」也没有 CLI 子命令，消息归档由 HyperKitty 插件在消息管道中自动完成，命令行层面与消息排障相关的是inject/qfile/unshunt三个队列工具。邮件命令通道（向listname-join@、listname-leave@发信完成订阅退订）是 CLI 之外的另一条用户自助通道，别名映射见 9.1 节。
2.3 命令树全量实测（mailman help）
以下为 mailman help 的完整实测回显，是本文一切子命令的权威清单：
Usage: mailman [OPTIONS] [COMMAND] [ARGS]...
The GNU Mailman mailing list management system Copyright 1998-2018 by the
Free Software Foundation, Inc. http://www.list.org
Options:
--version Show the version and exit.
--run-as-root Running mailman commands as root is not recommended and
mailman will refuse to run as root unless this option is
specified.
-C, --config FILE Configuration file to use. If not given, the environment
variable MAILMAN_CONFIG_FILE is consulted and used if
set. If neither are given, a default configuration file
is loaded.
-h, --help Show this message and exit.
Commands:
addmembers Add all member addresses in FILENAME with delivery mode...
admins Add and/or delete owners and moderators of a list.
aliases Regenerate the aliases appropriate for your MTA.
changeaddress Change a user's email address from old_address to...
conf Print the Mailman configuration.
create Create a mailing list.
delmembers Delete members from a mailing list.
digests Operate on digests.
findmember Display all memberships for a user or users with address...
gatenews Poll the NNTP server for messages to be gatewayed to...
help Show this help message and exit.
import21 Import Mailman 2.1 list data.
info Information about this Mailman instance.
inject Inject a message from a file into a mailing list's queue.
lists List all mailing lists.
members Display a mailing list's members.
notify Notify list owners/moderators of pending requests.
qfile Get information out of a queue file.
remove Remove a mailing list.
reopen Signal the Mailman processes to re-open their log files.
restart Stop and restart the Mailman runner subprocesses.
shell Operate on a mailing list.
start Start the Mailman master and runner processes.
status Show the current running status of the Mailman system.
stop Stop the Mailman master and runner processes.
syncmembers Add and delete members as necessary to syncronize a...
unshunt Unshunt messages.
version Display Mailman's version.
withlist Operate on a mailing list.
注意顶部的三个全局选项：--version、--run-as-root、-C/--config，它们必须放在子命令之前（如 mailman -C /etc/mailman3/mailman.cfg status），用法见 4.5 节。
三、前置条件
本文是专题篇，不重复安装步骤，但每个示例命令都必须能在已装好的服务器上独立执行。执行前确认以下四点：
- 已按 《Ubuntu 22.04 安装 Mailman 指南》 完成安装，Core 服务在跑；
- 当前 shell 不是 root，或使用
sudo -u mailman切换到专用用户； /opt/mailman/venv/bin/mailman可执行文件存在；- 配置文件路径为
/etc/mailman3/mailman.cfg（默认会自动加载，无需显式指定）。
用一条命令验证前置条件全部满足（回显即验证结果）：
sudo -u mailman /opt/mailman/venv/bin/mailman info
实测回显：
GNU Mailman 3.3.10 (Tom Sawyer)
Python 3.10.12 (main, Aug 31 2026, 10:18:17) [GCC 11.4.0]
config file: /etc/mailman3/mailman.cfg
db url: sqlite:////opt/mailman/var/data/mailman.db
devmode: DISABLED
REST root url: http://127.0.0.1:8001/3.1/
REST credentials: restadmin:q1w2e3r4
能打印出这 7 行即说明：版本正确、配置加载成功、数据库可读、REST API 就绪。
四、实例信息与服务生命周期命令
本节覆盖「看清实例状态」与「启停服务」两组命令。它们是日常巡检的第一站，也是排障时最先执行的命令。
4.1 info：实例信息与文件系统路径
info 打印实例的核心摘要；加 -v/--verbose 会额外列出全部文件系统路径，排障时非常有用：
sudo -u mailman /opt/mailman/venv/bin/mailman info -v
实测回显：
GNU Mailman 3.3.10 (Tom Sawyer)
Python 3.10.12 (main, Aug 31 2026, 10:18:17) [GCC 11.4.0]
config file: /etc/mailman3/mailman.cfg
db url: sqlite:////opt/mailman/var/data/mailman.db
devmode: DISABLED
REST root url: http://127.0.0.1:8001/3.1/
REST credentials: restadmin:q1w2e3r4
File system paths:
ARCHIVE_DIR = /opt/mailman/var/archives
BIN_DIR = /opt/mailman/venv/bin
CACHE_DIR = /opt/mailman/var/cache
CFG_FILE = /etc/mailman3/mailman.cfg
DATA_DIR = /opt/mailman/var/data
ETC_DIR = /opt/mailman/var/etc
LIST_DATA_DIR = /opt/mailman/var/lists
LOCK_DIR = /opt/mailman/var/locks
LOCK_FILE = /opt/mailman/var/locks/master.lck
LOG_DIR = /opt/mailman/var/logs
MESSAGES_DIR = /opt/mailman/var/messages
PID_FILE = /opt/mailman/var/master.pid
QUEUE_DIR = /opt/mailman/var/queue
TEMPLATE_DIR = /opt/mailman/var/templates
VAR_DIR = /opt/mailman/var
要点：PID_FILE（/opt/mailman/var/master.pid）与 LOCK_FILE（/opt/mailman/var/locks/master.lck）两个路径请记住，12 章的 systemd 排障实录会直接用到；info 还支持 -o FILENAME 把输出写到文件。
4.2 version 与 --version
版本号有两个入口，输出一致。子命令形式：
sudo -u mailman /opt/mailman/venv/bin/mailman version
实测回显：
GNU Mailman 3.3.10 (Tom Sawyer)
全局选项形式（无需进入子命令）：
sudo -u mailman /opt/mailman/venv/bin/mailman --version
实测回显：
GNU Mailman 3.3.10 (Tom Sawyer)
4.3 status
status 报告 master 守护进程是否在跑并给出其 PID，是巡检与排障的第一条命令：
sudo -u mailman /opt/mailman/venv/bin/mailman status
服务运行中的实测回显：
GNU Mailman is running (master pid: 8698)
服务停止后的实测回显（后文生命周期实验中采集）：
GNU Mailman is not running
💡 说明：master pid 每次启动都会变化，读者环境中的数字与本例不同属正常现象；判断服务是否健康看的是
is running与否，而非具体 PID。
4.4 start / stop / restart / reopen
四个进程管理子命令构成一组闭环：start 拉起 master 与全部 runner，stop 停掉它们，restart 只重启 runner 子进程（master 不动），reopen 通知各进程重新打开日志文件（配合日志轮转使用）。
先看参数表。start 的参数最多，实测如下：
sudo -u mailman /opt/mailman/venv/bin/mailman start --help
Usage: mailman start [OPTIONS]
Start the Mailman master and runner processes.
Options:
-f, --force If the master watcher finds an existing master
lock, it will normally exit with an error
message. With this option, the master will
perform an extra level of checking. If a process
matching the host/pid described in the lock file
is running, the master will still exit, requiring
you to manually clean up the lock. But if no
matching process is found, the master will remove
the apparently stale lock and make another
attempt to claim the master lock.
-g, --generate-alias-file Generate the MTA alias files upon startup. Some
MTA, like postfix, can't deliver email if alias
files mentioned in its configuration are not
present. In some situations, this could lead to a
deadlock at the first start of mailman3 server.
Setting this option to true will make this script
create the files and thus allow the MTA to
operate smoothly.
-u, --run-as-user Normally, this script will refuse to run if the
user id and group id are not set to the 'mailman'
user and group (as defined when you configured
Mailman). If run as root, this script will
change to this user and group before the check is
made. This can be inconvenient for testing and
debugging purposes, so the -u flag means that the
step that sets and checks the uid/gid is skipped,
and the program is run as the current user and
group. This flag is not recommended for normal
production environments. Note though, that if
you run with -u and are not in the mailman group,
you may have permission problems, such as being
unable to delete a list's archives through the
web. Tough luck!
-q, --quiet Don't print status messages. Error messages are
still printed to standard error.
-h, --help Show this message and exit.
其余三个子命令的参数表很短，实测回显依次如下。
stop --help：
Usage: mailman stop [OPTIONS]
Stop the Mailman master and runner processes.
Options:
-q, --quiet Don't print status messages. Error messages are still printed
to standard error.
-h, --help Show this message and exit.
restart --help：
Usage: mailman restart [OPTIONS]
Stop and restart the Mailman runner subprocesses.
Options:
-q, --quiet Don't print status messages. Error messages are still printed
to standard error.
-h, --help Show this message and exit.
reopen --help：
Usage: mailman reopen [OPTIONS]
Signal the Mailman processes to re-open their log files.
Options:
-q, --quiet Don't print status messages. Error messages are still printed
to standard error.
-h, --help Show this message and exit.
⚠️ 注意：若服务由 systemd 托管（如 3.4 节安装篇的
mailman3.service），不要手工执行mailman stop/mailman start——这会让 systemd 与实际进程脱钩并引发一连串启动失败。完整故障链与恢复流程见 12.2 节排障实录。restart/reopen不改变 master 进程，与 systemd 混用无此问题。
生命周期闭环实测（在受控窗口依次执行，每条命令独立运行）：
sudo -u mailman /opt/mailman/venv/bin/mailman stop
实测回显：
Shutting down Mailman's master runner
验证已停：
sudo -u mailman /opt/mailman/venv/bin/mailman status
实测回显：
GNU Mailman is not running
重新启动：
sudo -u mailman /opt/mailman/venv/bin/mailman start
实测回显：
Starting Mailman's master runner
Generating MTA alias maps
start 过程中会顺带生成 MTA 别名映射（对应 9.1 节的 aliases 能力）。验证已恢复：
sudo -u mailman /opt/mailman/venv/bin/mailman status
实测回显：
GNU Mailman is running (master pid: 8563)
restart 只重启 runner 子进程，master PID 保持不变：
sudo -u mailman /opt/mailman/venv/bin/mailman restart
实测回显：
Restarting the Mailman runners
验证 master 未换 PID：
sudo -u mailman /opt/mailman/venv/bin/mailman status
实测回显：
GNU Mailman is running (master pid: 8563)
reopen 通知各 runner 重开日志文件（配合 logrotate 使用）：
sudo -u mailman /opt/mailman/venv/bin/mailman reopen
实测回显：
Reopening the Mailman runners
4.5 全局选项 -C/--config 与 --run-as-root
两个全局选项都放在子命令之前。-C 显式指定配置文件（多实例或非默认路径时使用），--run-as-root 解除 root 运行限制。
-C 实测（显式指定默认配置文件，行为与省略时一致）：
sudo -u mailman /opt/mailman/venv/bin/mailman -C /etc/mailman3/mailman.cfg status
实测回显：
GNU Mailman is running (master pid: 8698)
--run-as-root 仅供确有必要的特殊场景，此处仅验证其存在性（参数表 2.3 节已给出），生产一律以 mailman 专用用户执行。
五、列表生命周期命令
建列表、列列表、删列表是最基础的管理动作，对应 create、lists、remove 三个子命令。
5.1 create：创建邮件列表
create 需要一个完整合法的投递地址作为列表名，域名必须已注册（未注册时默认行为是自动注册该域）。参数表实测如下：
sudo -u mailman /opt/mailman/venv/bin/mailman create --help
Usage: mailman create [OPTIONS] LISTNAME
Create a mailing list.
The 'fully qualified list name', i.e. the posting address of the mailing
list is required. It must be a valid email address and the domain must be
registered with Mailman. List names are forced to lower case.
Options:
--language CODE Set the list's preferred language to CODE,
which must be a registered two letter
language code.
-o, --owner OWNER Specify a list owner email address. If the
address is not currently registered with
Mailman, the address is registered and
linked to a user. Mailman will send a
confirmation message to the address, but it
will also send a list creation notice to the
address. More than one owner can be
specified.
--style-name NAME Specify a list style name.
-n, --notify / -no-notify, -N Notify the list owner by email that their
mailing list has been created.
-q, --quiet Print less output.
-d, --domain / -D, --no-domain Register the mailing list's domain if not
yet registered. This is the default
behavior, but these options are provided for
backward compatibility. With -D do not
register the mailing list's domain.
-h, --help Show this message and exit.
基础创建实测（自动注册 list.example.org 域）：
sudo -u mailman /opt/mailman/venv/bin/mailman create ops@list.example.org
实测回显：
Created mailing list: ops@list.example.org
创建时指定 owner 并静默输出（-q 让成功创建不打印任何内容，靠退出码 0 判断成功）：
sudo -u mailman /opt/mailman/venv/bin/mailman create -o newowner@example.org -q quiet-demo@list.example.org
实测回显：无输出（echo $? 为 0）。
验证 owner 已按参数挂上：
sudo -u mailman /opt/mailman/venv/bin/mailman members -R owner quiet-demo@list.example.org
实测回显：
newowner@example.org
重复创建同一列表会报错退出，实测回显：
Usage: mailman create [OPTIONS] LISTNAME
Try 'mailman create --help' for help.
Error: List already exists: ops@list.example.org
💡 说明：
-o/--owner可重复出现指定多个 owner；-n/--notify会给 owner 发创建通知邮件（依赖 MTA 出站已打通）。列表名强制小写，create Ops@list.example.org实际落库为ops@list.example.org。
5.2 lists：列出全部列表
lists 列出安装内所有列表，支持按域过滤与附加描述。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman lists --help
Usage: mailman lists [OPTIONS]
List all mailing lists.
Options:
-a, --advertised List only those mailing lists that are
publicly advertised
-n, --names / -N, --no-names Show also the list names
-d, --descriptions / -D, --no-descriptions
Show also the list descriptions
-q, --quiet Less verbosity
--domain DOMAIN List only those mailing lists hosted on the
given domain, which must be the email host
name. Multiple -d options may be given.
-h, --help Show this message and exit.
基础用法实测：
sudo -u mailman /opt/mailman/venv/bin/mailman lists
实测回显：
3 matching mailing lists found:
cli-demo@list.example.org
ops@list.example.org
test@list.example.org
按域过滤（--domain 值是邮箱主机名而非 Web 域名）：
sudo -u mailman /opt/mailman/venv/bin/mailman lists --domain list.example.org
实测回显：
3 matching mailing lists found:
cli-demo@list.example.org
ops@list.example.org
test@list.example.org
5.3 remove：删除邮件列表
remove 删除列表及其配置（归档目录默认保留，可按需手工清理）。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman remove --help
Usage: mailman remove [OPTIONS] LISTSPEC
Remove a mailing list.
Options:
-q, --quiet Suppress status messages
-h, --help Show this message and exit.
删除实测（以前一小节创建的演示列表为目标）：
sudo -u mailman /opt/mailman/venv/bin/mailman remove quiet-demo@list.example.org
实测回显：
Removed list: quiet-demo@list.example.org
验证已删：
sudo -u mailman /opt/mailman/venv/bin/mailman lists
实测回显：
3 matching mailing lists found:
cli-demo@list.example.org
ops@list.example.org
test@list.example.org
六、成员与角色管理命令
这是 CLI 使用频率最高的一组命令：addmembers/delmembers 承担订阅与退订，members 查询与过滤，admins 管 owner/moderator，syncmembers 整表同步，changeaddress/findmember 处理地址变更与查找。
6.1 addmembers：批量添加成员（含邀请模式）
addmembers 从文件或标准输入批量添加成员。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman addmembers --help
Usage: mailman addmembers [OPTIONS] FILENAME LISTSPEC
Add all member addresses in FILENAME with delivery mode as specified with
-d/--delivery. FILENAME can be '-' to indicate standard input. Blank lines
and lines that start with a '#' are ignored.
Options:
-d, --delivery [regular|mime|plain|summary|disabled]
Set the added members delivery mode to
'regular', 'mime', 'plain', 'summary' or
'disabled'. I.e., one of regular, three
modes of digest or no delivery. If not
given, the default is regular. Ignored for
invited members.
-i, --invite Send the added members an invitation rather
than immediately adding them.
-w, --welcome-msg / -W, --no-welcome-msg
Override the list's setting for
send_welcome_message.
-h, --help Show this message and exit.
💡 技术拓展：
-d/--delivery的五种投递模式是理解成员模型的关键，对比如下——
模式 含义 适用场景 regular单发即时投递（默认） 普通讨论组成员 mimeMIME 捆绑摘要，攒批发送 接受 HTML/附件内容的读者 plain纯文本（RFC 1153）摘要 追求纯净文本的读者 summary仅主题目录摘要（无正文） 只想看都聊了什么的观察者 disabled暂停投递但保留成员身份 休假的成员、只读观察者
mime/plain/summary三者统称摘要（digest）成员，与regular相对；本文 6.3 节的members -d过滤与第七章的digests命令都以这套模式为基础。CLI 批量添加默认regular。
从标准输入批量添加两个成员（- 表示 stdin；空行与 # 注释行自动忽略）：
printf "frank@example.org\ngrace@example.org\n" | sudo -u mailman /opt/mailman/venv/bin/mailman addmembers - ops@list.example.org
实测回显：无输出（静默成功）。
验证：
sudo -u mailman /opt/mailman/venv/bin/mailman members ops@list.example.org
实测回显：
frank@example.org
grace@example.org
以摘要模式添加成员（-d mime）：
printf "heidi@example.org\n" | sudo -u mailman /opt/mailman/venv/bin/mailman addmembers -d mime - ops@list.example.org
实测回显：无输出。
⚠️ 注意：
addmembers成功时不输出任何内容，操作结果必须用members命令回查确认——这是「命令+验证」闭环在这里的具体含义。CLI 直接添加不走确认流程，成员立即生效；而-i/--invite会改走邀请流程：向目标地址发邀请邮件，对方确认后才真正加入（这就是 Core CLI 的「邀请订阅」入口）。
6.2 delmembers：删除成员
delmembers 支持单地址、文件批量、清空全列表与跨全安装删除四种姿势。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman delmembers --help
Usage: delmembers [OPTIONS]
Delete members from a mailing list.
Options:
-l, --list LISTSPEC The list to operate on. Required unless
--fromall is specified.
-f, --file FILENAME Delete list members whose addresses are in
FILENAME in addition to those specified with
-m/--member if any. FILENAME can be '-' to
indicate standard input. Blank lines and
lines that start with a '#' are ignored.
-m, --member ADDRESS Delete the list member whose address is
ADDRESS in addition to those specified with
-f/--file if any. This option may be
repeated for multiple addresses.
-a, --all Delete all the members of the list. If
specified, none of -f/--file, -m/--member or
--fromall may be specified.
--fromall Delete the member(s) specified by
-m/--member and/or -f/--file from all lists
in the installation. This may not be
specified together with -a/--all or
-l/--list.
-g, --goodbye-msg / -G, --no-goodbye-msg
Override the list's setting for
send_goodbye_message to deleted members.
-n, --admin-notify / -N, --no-admin-notify
Override the list's setting for
admin_notify_mchanges.
-h, --help Show this message and exit.
单地址删除实测：
sudo -u mailman /opt/mailman/venv/bin/mailman delmembers -l ops@list.example.org -m grace@example.org
实测回显：无输出。
验证删除生效：
sudo -u mailman /opt/mailman/venv/bin/mailman members ops@list.example.org
实测回显：
frank@example.org
heidi@example.org
清空全列表成员实测（-a 与 -l 必须同给，且不能再混用 -f/-m）：
sudo -u mailman /opt/mailman/venv/bin/mailman delmembers -l ops@list.example.org -a
实测回显：无输出。
验证已清空（注意提示语用的是 list_id 形式，@ 换成了 .）：
sudo -u mailman /opt/mailman/venv/bin/mailman members ops@list.example.org
实测回显：
ops.list.example.org has no members
💡 说明：
--fromall是「从这个人名下所有列表中除名」的全局清理动作，适合处理离职成员；-g/-G与-n/-N可临时覆盖列表的发退订信/管理员通知设置。
6.3 members：查询成员（多维度过滤）
members 是成员查询的主力，支持按角色、投递模式、投递状态过滤。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman members --help
Usage: mailman members [OPTIONS] LISTSPEC
Display a mailing list's members. Filtering along various criteria can be
done when displaying. With no options given, displaying mailing list members
to stdout is the default mode.
Options:
-a, --add FILENAME [MODE] Add all member addresses in FILENAME.
This option is removed. Use 'mailman
addmembers' instead.
-x, --delete FILENAME [MODE] Delete all member addresses found in
FILENAME. This option is removed. Use
'mailman delmembers' instead.
-s, --sync FILENAME [MODE] Synchronize all member addresses of
the specified mailing list with the member
addresses found in FILENAME. This option is
removed. Use 'mailman syncmembers' instead.
-o, --output FILENAME Display output to FILENAME instead of
stdout. FILENAME can be '-' to indicate
standard output.
-R, --role [any|owner|moderator|nonmember|member|administrator]
Display only members with a given ROLE. The
role may be 'any', 'member', 'nonmember',
'owner', 'moderator', or 'administrator'
(i.e. owners and moderators). If not given,
then 'member' role is assumed.
-r, --regular Display only regular delivery members.
-e, --email-only Display member addresses only, without the
display name.
-c, --count-only Display members count only.
-N, --no-change This option has no effect. It exists for
backwards compatibility only.
-d, --digest kind Display only digest members of kind. 'any'
means any digest type, 'plaintext' means
only plain text (rfc 1153) type digests,
'mime' means MIME type digests.
-n, --nomail WHY Display only members with a given delivery
status. 'enabled' means all members whose
delivery is enabled, 'any' means members
whose delivery is disabled for any reason,
'byuser' means that the member disabled
their own delivery, 'bybounces' means that
delivery was disabled by the automated
bounce processor, 'byadmin' means delivery
was disabled by the list administrator or
moderator, and 'unknown' means that delivery
was disabled for unknown (legacy) reasons.
-h, --help Show this message and exit.
💡 说明：
-a/-x/-s三个 MODE 选项已被移除（帮助文本明确指向替代命令addmembers/delmembers/syncmembers），老脚本从 Mailman 2 迁移时要改写；-R administrator表示 owner+moderator 合集，-R nonmember是「曾发过信的非成员」名单。
常用过滤实测。先给 ops 列表重建三个成员（2 个 regular + 1 个 mime 摘要）：
printf "frank@example.org\ngrace@example.org\n" | sudo -u mailman /opt/mailman/venv/bin/mailman addmembers - ops@list.example.org
printf "heidi@example.org\n" | sudo -u mailman /opt/mailman/venv/bin/mailman addmembers -d mime - ops@list.example.org
仅列摘要成员：
sudo -u mailman /opt/mailman/venv/bin/mailman members -d mime ops@list.example.org
实测回显：
heidi@example.org
仅输出成员数量：
sudo -u mailman /opt/mailman/venv/bin/mailman members -c ops@list.example.org
实测回显：
3
仅输出邮箱地址（无显示名）：
sudo -u mailman /opt/mailman/venv/bin/mailman members -e ops@list.example.org
实测回显：
frank@example.org
grace@example.org
heidi@example.org
角色过滤实测（owner 与 moderator 的实际效果见 6.4 节的操作后回查）。
6.4 admins：管理 owner 与 moderator
admins 专职增删两类管理角色。不带 -a/-d 运行会直接报错，这个行为本身就值得记住。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman admins --help
Usage: mailman admins [OPTIONS] LISTSPEC
Add and/or delete owners and moderators of a list.
Options:
-a, --add TEXT User to add with the given role. This may be
an email address or, if quoted, any display
name and email address parseable by
email.utils.parseaddr. E.g., 'Jane Doe
<jane@example.com>'. May be repeated to add
multiple users.
-d, --delete TEXT Email address of the user to be removed from
the given role. May be repeated to delete
multiple users.
-r, --role [owner|moderator] The role to add/delete. This may be 'owner' or
'moderator'. If not given, then 'owner' role
is assumed.
-h, --help Show this message and exit.
空参数运行的实测报错：
sudo -u mailman /opt/mailman/venv/bin/mailman admins ops@list.example.org
Usage: mailman admins [OPTIONS] LISTSPEC
Try 'mailman admins --help' for help.
Error: Nothing to add or delete.
添加 owner 实测：
sudo -u mailman /opt/mailman/venv/bin/mailman admins -a ops-owner@example.org ops@list.example.org
实测回显：无输出。
添加 moderator 实测（-r 缺省为 owner，加 moderator 必须显式指定）：
sudo -u mailman /opt/mailman/venv/bin/mailman admins -r moderator -a mod1@example.org ops@list.example.org
实测回显：无输出。
用 members -R 回查两类角色：
sudo -u mailman /opt/mailman/venv/bin/mailman members -R owner ops@list.example.org
实测回显：
ops-owner@example.org
sudo -u mailman /opt/mailman/venv/bin/mailman members -R moderator ops@list.example.org
实测回显：
mod1@example.org
删除 owner 实测：
sudo -u mailman /opt/mailman/venv/bin/mailman admins -d ops-owner@example.org ops@list.example.org
实测回显：无输出。
回查确认已删：
sudo -u mailman /opt/mailman/venv/bin/mailman members -R owner ops@list.example.org
实测回显：
ops.list.example.org has no members
6.5 syncmembers：成员名单整表同步
syncmembers 把列表成员同步成与输入文件完全一致：文件里没有的删掉、文件里有而列表没有的加上。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman syncmembers --help
Usage: mailman syncmembers [OPTIONS] FILENAME LISTSPEC
Add and delete members as necessary to syncronize a list's membership with
an input file. FILENAME is the file containing the new membership, one
member per line. Blank lines and lines that start with a '#' are ignored.
Addresses in FILENAME which are not current list members will be added to
the list with delivery mode as specified with -d/--delivery. List members
whose addresses are not in FILENAME will be removed from the list. FILENAME
can be '-' to indicate standard input.
Options:
-d, --delivery [regular|mime|plain|summary|disabled]
Set the added members delivery mode to
'regular', 'mime', 'plain', 'summary' or
'disabled'. I.e., one of regular, three
modes of digest or no delivery. If not
given, the default is regular.
-w, --welcome-msg / -W, --no-welcome-msg
Override the list's setting for
send_welcome_message to added members.
-g, --goodbye-msg / -G, --no-goodbye-msg
Override the list's setting for
send_goodbye_message to deleted members.
-a, --admin-notify / -A, --no-admin-notify
Override the list's setting for
admin_notify_mchanges.
-n, --no-change Don't actually make the changes. Instead,
print out what would be done to the list.
-h, --help Show this message and exit.
准备同步源文件（含一个 # 注释行与一个空行，验证解析规则）：
printf "frank@example.org\nhank@example.org\n# comment line\n\niris@example.org\n" | sudo tee /opt/mailman/tmp-sync.txt >/dev/null
sudo chown mailman: /opt/mailman/tmp-sync.txt
先 -n 干跑，只打印将要发生的变更而不动库：
sudo -u mailman /opt/mailman/venv/bin/mailman syncmembers -n /opt/mailman/tmp-sync.txt ops@list.example.org
实测回显：
[ADD] frank@example.org
[ADD] hank@example.org
[ADD] iris@example.org
确认干跑结果符合预期后真实执行：
sudo -u mailman /opt/mailman/venv/bin/mailman syncmembers /opt/mailman/tmp-sync.txt ops@list.example.org
实测回显：
[ADD] frank@example.org
[ADD] hank@example.org
[ADD] iris@example.org
回查成员（此刻 grace/heidi 已不在文件里，会被同步删除；frank 保留）：
sudo -u mailman /opt/mailman/venv/bin/mailman members ops@list.example.org
实测回显：
frank@example.org
hank@example.org
iris@example.org
💡 说明：
[ADD]之外同步删除成员时会输出[DELETE]行；把成员名单放进版本库或 HR 系统、再用 cron 定期syncmembers，是社区常用的人员名单自动化治理方案。干跑-n是这类自动化上生产前的必做步骤。
6.6 changeaddress：变更成员地址
changeaddress 把一个地址在全安装范围内的所有成员关系改到新地址，返回新地址时保留大小写。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman changeaddress --help
Usage: mailman changeaddress [OPTIONS] OLD_ADDRESS NEW_ADDRESS
Change a user's email address from old_address to possibly case-preserved
new_address.
Options:
-h, --help Show this message and exit.
实测（把 ops 列表成员 frank@example.org 改为 frank2@example.org）：
sudo -u mailman /opt/mailman/venv/bin/mailman changeaddress frank@example.org frank2@example.org
实测回显：
Address changed from frank@example.org to frank2@example.org.
6.7 findmember：全局查找成员
findmember 按模式串在全安装的所有列表、所有角色里找成员关系，模式串会被转成 SQL 通配查询，简单字符串最好用。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman findmember --help
Usage: mailman findmember [OPTIONS] PATTERN
Display all memberships for a user or users with address matching a pattern.
Because part of the process involves converting the pattern to a SQL query
with wildcards, the pattern should be simple. A simple string works best.
Options:
-r, --role [all|owner|moderator|nonmember|member|administrator]
Display only memberships with the given
role. If not given, 'all' role, i.e. all
roles, is the default.
-h, --help Show this message and exit.
按前缀查单个用户实测：
sudo -u mailman /opt/mailman/venv/bin/mailman findmember frank
实测回显：
Email: frank2@example.org
List: ops.list.example.org
MemberRole.member
按域名查全量成员关系实测（可看到成员/管理员/版主各角色混排）：
sudo -u mailman /opt/mailman/venv/bin/mailman findmember example.org
实测回显：
Email: alice@example.org
List: test.list.example.org
MemberRole.member
Email: bob@mbox.example.org
List: test.list.example.org
MemberRole.member
Email: frank2@example.org
List: ops.list.example.org
MemberRole.member
Email: hank@example.org
List: ops.list.example.org
MemberRole.member
Email: iris@example.org
List: ops.list.example.org
MemberRole.member
Email: mod1@example.org
List: ops.list.example.org
MemberRole.moderator
Email: owner@example.org
List: cli-demo.list.example.org
MemberRole.owner
Email: user2@example.org
List: cli-demo.list.example.org
MemberRole.member
Email: user3@example.org
List: cli-demo.list.example.org
MemberRole.member
注意输出里的列表标识是 list_id 形式（test.list.example.org），角色名带 MemberRole. 前缀，均照实记录。
七、摘要管理命令 digests
digests 用于手工干预摘要生成：立即发送攒批中的摘要、递增卷号、dry-run 预演。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman digests --help
Usage: mailman digests [OPTIONS]
Operate on digests.
Options:
-l, --list list Operate on this mailing list. Multiple --list options can
be given. The argument can either be a List-ID or a fully
qualified list name. Without this option, operate on the
digests for all mailing lists.
-s, --send Send any collected digests right now, even if the size
threshold has not yet been met.
-b, --bump Increment the digest volume number and reset the digest
number to one. If given with --send, the volume number is
incremented before any current digests are sent.
-n, --dry-run Don't actually do anything, but in conjunction with
--verbose, show what would happen.
-p, --periodic Send any collected digests for the List only if their
digest_send_periodic is set to True.
-h, --help Show this message and exit.
-b 递增卷号实测（卷号/序号状态一并打印）：
sudo -u mailman /opt/mailman/venv/bin/mailman digests -l quiet-demo@list.example.org -b -v
实测回显：
quiet-demo.list.example.org is at volume 1, number 1
quiet-demo.list.example.org bumped to volume 1, number 2
-n dry-run 实测（列表无攒批摘要时无任何输出，属正常）：
sudo -u mailman /opt/mailman/venv/bin/mailman digests -l test@list.example.org -v -n
实测回显：无输出。
💡 说明：摘要的攒批触发由 runner 周期任务完成（大小阈值/周期到达自动发送），
digests -s是「不等阈值立刻发」的人工入口；-b通常在年度或卷册切换时使用，让volume归位、number从 1 重新计数。-l可重复传多个列表，省略-l则作用于全部列表。
八、队列与消息排障命令
Core 的消息流转全部经过 /opt/mailman/var/queue/ 下的 12 个队列目录。inject/qfile/unshunt 是命令行层面排障消息卡点的三件套，本节用一条「注入 shunt 队列 → 解析 → 丢弃」的完整闭环演示三者的配合。
8.1 inject：向队列注入消息
inject 把一份 RFC 2822 格式的消息文件投进指定队列，默认进入 in（入站管道）队列。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman inject --help
Usage: mailman inject [OPTIONS] LISTSPEC
Inject a message from a file into a mailing list's queue.
Options:
-q, --queue TEXT The name of the queue to inject the message to.
QUEUE must be one of the directories inside the
queue directory. If omitted, the incoming queue
is used.
-s, --show Show a list of all available queue names and exit.
-f, --filename FILENAME Name of file containing the message to inject. If
not given, or '-' (without the quotes) standard
input is used.
-m, --metadata KEY=VALUE Additional metadata key/value pairs to add to the
message metadata dictionary. Use the format
key=value. Multiple -m options are allowed.
-h, --help Show this message and exit.
先看实例里有哪些队列可用：
sudo -u mailman /opt/mailman/venv/bin/mailman inject --show
实测回显：
Available queues:
archive
bad
bounces
command
digest
in
nntp
out
pipeline
retry
shunt
virgin
准备一封演示消息并注入 shunt 队列（shunt 是「处理出错被搁置」的暂存队列，注入后消息以 .pck 文件躺在目录里等待人工处理，正好用于演示且不会触发真实投递）：
printf "From: alice@example.org\nTo: test@list.example.org\nSubject: qfile demo message\nMessage-ID: <qfile-demo-1@example.org>\nDate: Tue, 21 Oct 2026 05:00:00 +0000\n\nHello from the inject demo.\n" | sudo tee /opt/mailman/tmp-msg.txt >/dev/null
sudo chown mailman: /opt/mailman/tmp-msg.txt
sudo -u mailman /opt/mailman/venv/bin/mailman inject -q shunt -f /opt/mailman/tmp-msg.txt test@list.example.org
实测回显：无输出。验证消息已落队列目录：
sudo ls -la /opt/mailman/var/queue/shunt/
实测回显：
total 12
drwxrwx--- 2 mailman mailman 4096 Oct 21 06:44 .
drwxr-xr-x 14 mailman mailman 4096 Oct 21 06:44 ..
-rw-rw---- 1 mailman mailman 619 Oct 21 06:44 1792565041.525739+8cd504232378dd124c3281595b2c4856b6cdbc30.pck
8.2 qfile：解析队列 .pck 文件
qfile 把队列里的 pickle 文件解开并以可读形式打印，是排查「消息为什么卡住」的核心工具。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman qfile --help
Usage: mailman qfile [OPTIONS] QFILE
Get information out of a queue file.
Options:
-p, --print / -n, --no-print Don't attempt to pretty print the object.
This is useful if there is some problem with
the object and you just want to get an
unpickled representation. Useful with
'mailman qfile -i <file>'. In that case, the
list of unpickled objects will be left in a
variable called 'm'.
-i, --interactive Start an interactive Python session, with a
variable called 'm' containing the list of
unpickled objects.
-h, --help Show this message and exit.
对上一步的 .pck 文件实测（文件名以实际目录内容为准）：
sudo -u mailman /opt/mailman/venv/bin/mailman qfile /opt/mailman/var/queue/shunt/1792565041.525739+8cd504232378dd124c3281595b2c4856b6cdbc30.pck
实测回显：
[----- start pickle -----]
<----- start object 1 ----->
From: alice@example.org
To: test@list.example.org
Subject: qfile demo message
Message-ID: <qfile-demo-1@example.org>
Date: Tue, 21 Oct 2026 05:00:00 +0000
Message-ID-Hash: HOVTPNTSAMTLFDOJ5GNTOMOQ3FPYEJBR
X-Message-ID-Hash: HOVTPNTSAMTLFDOJ5GNTOMOQ3FPYEJBR
Hello from the inject demo.
<----- start object 2 ----->
{ '_parsemsg': False,
'listid': 'test.list.example.org',
'original_size': 286,
'version': 3}
[----- end pickle -----]
输出分两个对象：对象 1 是消息本体（含 Mailman 附加的 Message-ID-Hash 头），对象 2 是元数据字典（目标列表、原始大小、pickle 版本）。
8.3 unshunt：处理被搁置的消息
unshunt 把 shunt 队列的消息搬回原队列重试，或加 -d 直接丢弃。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman unshunt --help
Usage: mailman unshunt [OPTIONS]
Unshunt messages.
Options:
-d, --discard Discard all shunted messages instead of moving them back to
their original queue.
-h, --help Show this message and exit.
丢弃演示消息完成闭环实测：
sudo -u mailman /opt/mailman/venv/bin/mailman unshunt -d
实测回显：无输出。验证队列已清空：
sudo ls -la /opt/mailman/var/queue/shunt/
实测回显：
total 8
drwxrwx--- 2 mailman mailman 4096 Oct 21 06:44 .
drwxr-xr-x 14 mailman mailman 4096 Oct 21 06:44 ..
8.4 notify：催办待审请求
notify 给 owner/moderator 重发一封「有待处理请求」的提醒邮件。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman notify --help
Usage: mailman notify [OPTIONS]
Notify list owners/moderators of pending requests.
Options:
-l, --list list Operate on this mailing list. Multiple --list options can
be given. The argument can either be a List-ID or a fully
qualified list name. Without this option, operate on the
requests for all mailing lists.
-n, --dry-run Don't actually do anything, but in conjunction with
--verbose, show what would happen.
-v, --verbose Print some additional status.
-h, --help Show this message and exit.
实测（列表当前没有待审请求，命令静默返回）：
sudo -u mailman /opt/mailman/venv/bin/mailman notify -l test@list.example.org
实测回显：无输出。
💡 说明：待审请求（订阅确认、持审消息）的处置在 Postorius Web 界面或 REST API 完成，
notify只负责催办提醒。命令静默代表没有可催办的对象，非异常。
九、MTA 别名与配置查看命令
本节三个命令分别负责：生成 MTA 别名映射文件、按节/键查看配置、以及 NNTP 网关的手动触发防护。
9.1 aliases：生成 MTA 别名映射文件
aliases 依据当前列表数据重新生成 Postfix 所需的两个映射文件（postfix_lmtp 收件映射、postfix_domains 域映射）及其 .db 哈希副本。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman aliases --help
Usage: mailman aliases [OPTIONS]
Regenerate the aliases appropriate for your MTA.
Options:
-d, --directory DIRECTORY An alternative directory to output the various
MTA files to.
-h, --help Show this message and exit.
不带参数运行时，文件直接重写到配置指定的生效目录（本文环境为 /opt/mailman/var/data/），命令本身静默。用 -d 输出到指定目录观察生成产物（目录必须预先存在，实测对不存在目录的报错见 12.6 节）：
sudo mkdir -p /tmp/aliasout
sudo chown mailman: /tmp/aliasout
sudo -u mailman /opt/mailman/venv/bin/mailman aliases -d /tmp/aliasout
sudo ls -la /tmp/aliasout/
实测回显：
total 32
drwxr-xr-x 2 mailman mailman 120 Oct 21 06:45 .
drwxrwxrwt 10 root root 240 Oct 21 06:45 ..
-rw-rw---- 1 mailman mailman 349 Oct 21 06:45 postfix_domains
-rw-r----- 1 mailman mailman 12288 Oct 21 06:45 postfix_domains.db
-rw-rw---- 1 mailman mailman 2223 Oct 21 06:45 postfix_lmtp
-rw-r----- 1 mailman mailman 12288 Oct 21 06:45 postfix_lmtp.db
postfix_lmtp 内容节选（文件头注释 + 各列表的收件地址到 LMTP 端口的映射行）：
# AUTOMATICALLY GENERATED BY MAILMAN ON 2026-10-21 06:45:40
#
# This file is generated by Mailman, and is kept in sync with the binary hash
# file. YOU SHOULD NOT MANUALLY EDIT THIS FILE unless you know what you're
# doing, and can keep the two files properly in sync. If you screw it up,
# you're on your own.
cli-demo@list.example.org lmtp:[127.0.0.1]:8024
cli-demo-bounces@list.example.org lmtp:[127.0.0.1]:8024
cli-demo-confirm@list.example.org lmtp:[127.0.0.1]:8024
cli-demo-join@list.example.org lmtp:[127.0.0.1]:8024
cli-demo-leave@list.example.org lmtp:[127.0.0.1]:8024
cli-demo-owner@list.example.org lmtp:[127.0.0.1]:8024
cli-demo-request@list.example.org lmtp:[127.0.0.1]:8024
cli-demo-subscribe@list.example.org lmtp:[127.0.0.1]:8024
cli-demo-unsubscribe@list.example.org lmtp:[127.0.0.1]:8024
每个列表固定生成 9 条映射：投递主地址加 -bounces/-confirm/-join/-leave/-owner/-request/-subscribe/-unsubscribe 八个功能后缀地址，全部指向 Core 的 LMTP 端口。文件头明确警示「自动生成，勿手工编辑」——改列表后重跑 mailman aliases 即可，Postfix 侧无需任何手动干预。
9.2 conf：查看生效配置
conf 打印运行时生效的配置键值，支持按节（-s）与按键（-k）查询，是核对「改的配置到底生效没有」的标准手段。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman conf --help
Usage: mailman conf [OPTIONS]
Print the Mailman configuration.
Options:
-o, --output FILENAME File to send the output to. If not given, or if '-'
is given, standard output is used.
-s, --section TEXT Section to use for the lookup. If no key is given,
all the key-value pairs of the given section will be
displayed.
-k, --key TEXT Key to use for the lookup. If no section is given,
all the key-values pair from any section matching the
given key will be displayed.
-h, --help Show this message and exit.
按节查询实测（[mailman] 主节全量键值，输出节选——节选边界为真实输出中的完整键值行）：
sudo -u mailman /opt/mailman/venv/bin/mailman conf -s mailman
实测回显（节选）：
[mailman] anonymous_list_keep_headers: ^x-mailman- ^x-content-filtered-by: ^x-topics:
^x-ack: ^x-beenthere: ^x-list-administrivia: ^x-spam-
[mailman] cache_life: 7d
[mailman] check_max_size_on_filtered_message: no
[mailman] default_language: en
[mailman] dsn_lifetime: 1d
[mailman] email_commands_max_lines: 10
[mailman] filter_report: no
[mailman] filtered_messages_are_preservable: no
[mailman] hold_digest: no
[mailman] html_to_plain_text_command: /usr/bin/lynx -dump $filename
[mailman] layout: custom
[mailman] listname_chars: [-_.0-9a-z]
[mailman] masthead_threshold: 4
[mailman] moderator_request_life: 180d
[mailman] noreply_address: noreply
[mailman] pending_request_life: 3d
[mailman] post_hook:
[mailman] pre_hook:
[mailman] run_tasks_every: 1h
[mailman] sender_headers: from from_ reply-to sender
[mailman] site_owner: admin@example.org
按键查询实测（跨节找所有名为 layout 的键）：
sudo -u mailman /opt/mailman/venv/bin/mailman conf -k layout
实测回显：
[mailman] layout: custom
MTA 对接参数节选（-s mta，与 Postfix/LMTP 排障直接相关的键）：
[mta] configuration: /opt/mailman/etc/postfix-mailman.cfg
[mta] incoming: mailman.mta.postfix.LMTP
[mta] lmtp_host: 127.0.0.1
[mta] lmtp_port: 8024
[mta] outgoing: mailman.mta.deliver.deliver
[mta] smtp_host: 127.0.0.1
[mta] smtp_port: 25
💡 说明：
conf输出的键名即mailman.cfg的合法键名（配置文件的逐段详解见 《Mailman 3.3.10 配置参数详解》），-s/-k查询结果就是修改后验证生效性的「真值来源」——它读的是运行时实际加载的值而非文件原文。
9.3 gatenews：NNTP 网关拉取（防误跑设计）
gatenews 从 NNTP 服务器拉取需网关到列表的新闻组消息。它由 nntp runner 周期执行，手工直接运行会被拒绝——这是防误跑的显式设计，实测回显：
sudo -u mailman /opt/mailman/venv/bin/mailman gatenews
Usage: mailman gatenews [OPTIONS]
Try 'mailman gatenews --help' for help.
Error: The gatenews command is run periodically by the nntp runner.
If you are running it via cron, you should remove it from the crontab.
If you want to run it manually, set _MAILMAN_GATENEWS_NNTP in the
environment.
错误信息本身就是操作指引：cron 里不该再挂它（会与 runner 重复跑）；确要手工运行需设置 _MAILMAN_GATENEWS_NNTP 环境变量。未启用 NNTP 网关的部署可无视此命令。
十、Python 交互与数据迁移命令
10.1 shell 与 withlist：Python 交互式操作
shell 与 withlist 是同一命令的两个名字（后者沿用 Mailman 2 的习惯叫法），提供带完整 Core 环境的 Python 交互/脚本能力。参数表实测（两个命令输出一致，此处以 shell 为例）：
sudo -u mailman /opt/mailman/venv/bin/mailman shell --help
Usage: mailman shell [OPTIONS] [RUN_ARGS]...
Operate on a mailing list.
For detailed help, see --details
Options:
-i, --interactive Leaves you at an interactive prompt after all other
processing is complete. This is the default unless the
--run option is given.
-r, --run TEXT Run a script. The argument is the module path to a
callable. This callable will be imported and then, if
--listspec/-l is also given, is called with the mailing
list as the first argument. If additional arguments
are given at the end of the command line, they are
passed as subsequent positional arguments to the
callable. For additional help, see --details. If no
--listspec/-l argument is given, the script function
being called is called with no arguments.
--details Print detailed instructions and exit.
-l, --listspec TEXT A specification of the mailing list to operate on.
This may be the posting address of the list, or its
List-ID. The argument can also be a Python regular
expression, in which case it is matched against both
the posting address and List-ID of all mailing lists.
To use a regular expression, LISTSPEC must start with a
^ (and the matching is done with re.match(). LISTSPEC
cannot be a regular expression unless --run is given.
-h, --help Show this message and exit.
绑定列表的交互实测（-l 指定列表后，变量 m 即该列表对象，管道喂入脚本逐行执行）：
printf "print(m.posting_address)\nprint(m.display_name)\nprint(m.description)\ncommit()\n" | sudo -u mailman /opt/mailman/venv/bin/mailman shell -l test@list.example.org
实测回显：
Welcome to the GNU Mailman shell
Use commit() to commit changes.
Use abort() to discard changes since the last commit.
Exit with ctrl+D does an implicit commit() but exit() does not.
The variable 'm' is the test@list.example.org mailing list
>>> test@list.example.org
>>> Test
>>>
三个关键点（都来自实测）：m 是列表对象、改动要 commit() 才落库、ctrl+D 退出隐式 commit 而 exit() 不落库。不带 -l 时 m 为 None，任何 m.xxx 访问都会报 AttributeError——完整报错与恢复办法见 12.4 节。
-r 脚本模式适合批量运维：把操作写成 Python 函数（第一个参数为列表对象），mailman shell -r 模块路径 -l 列表地址 [附加参数...] 调用，--details 输出里有完整示例（含 def listaddr(mlist): print(mlist.posting_address) 这样的模板）。
10.2 import21：从 Mailman 2.1 迁移列表数据
import21 把 Mailman 2.1 时代的列表配置 pickle 文件（config.pck）导入 Core。参数表实测：
sudo -u mailman /opt/mailman/venv/bin/mailman import21 --help
Usage: mailman import21 [OPTIONS] LISTSPEC PICKLE_FILE
Import Mailman 2.1 list data. Requires the fully-qualified name of the list
to import and the path to the Mailman 2.1 pickle file.
Options:
-c, --charset TEXT Specify the encoding of strings in PICKLE_FILE if not
utf-8 or a subset thereof. This will normally be the
Mailman 2.1 charset of the list's preferred_language.
-h, --help Show this message and exit.
标准用法形态（先在 Core 侧 create 好同名空列表，再导入旧数据）：
sudo -u mailman /opt/mailman/venv/bin/mailman create legacy@list.example.org
sudo -u mailman /opt/mailman/venv/bin/mailman import21 legacy@list.example.org /path/to/mailman21/lists/legacy/config.pck
⚠️ 注意：
PICKLE_FILE是 Mailman 2.1 服务器上~mailman/lists/<列表名>/config.pck的拷贝，需先迁移到本机并让mailman用户可读；-c用于旧列表字符集非 UTF-8 的场景（如 gb2312）。本文环境无 Mailman 2.1 遗留数据，未执行真实导入，以上为官方参数语义与调用形态；归档数据（mbox）迁移走 HyperKitty 的导入工具，不属于 Core CLI 范畴。
十一、注意事项
以下要点均来自实测行为，写脚本与日常操作前先过一遍：
- root 一律被拒：Core 所有命令在 root 下直接报错（见 2.1 节回显），统一
sudo -u mailman执行。 - systemd 托管下禁手工 start/stop：
mailman stop/start与 systemd 单位脱钩后会引发启动失败连锁（现象、诊断、恢复全流程见 12.2 节）；托管部署一律systemctl操作，restart/reopen不受此限。 - 子命令帮助的正确姿势是
<子命令> --help：mailman help <子命令>形式不存在（实测报错见 12.1 节），mailman help只能整体打印命令树。 - 增删命令静默成功：
addmembers/delmembers/admins/create -q/inject/unshunt成功时无任何输出，脚本里必须靠退出码 + 回查命令闭环确认，不能「没报错就当成功」而不验证。 - listspec 的两种形态：多数命令接受投递地址（
test@list.example.org）；digests/notify的-l还接受 List-ID（test.list.example.org）；而members对空列表的提示、findmember的输出统一用 list_id 形式（@换.）。 - 全局选项在子命令之前：
mailman -C /path/to/mailman.cfg status合法，mailman status -C ...不合法。 delmembers -a与--fromall互斥：前者清空指定列表，后者跨全安装除名，不可同传；批量删除前先members回看名单。syncmembers先干跑：-n输出的[ADD]/[DELETE]清单就是将来真实执行的清单，自动化同步务必把干跑纳入流程。
十二、常见问题
12.1 mailman help create 为什么报错？
现象：
sudo -u mailman /opt/mailman/venv/bin/mailman help create
实测回显：
Usage: mailman help [OPTIONS]
Try 'mailman help --help' for help.
Error: Got unexpected extra argument (create)
定位：mailman help 子命令不接收额外参数，Click 框架把它当成了多余的位置参数。解决：子命令的帮助一律用 mailman <子命令> --help（如 mailman create --help），mailman help 只用于整体命令树。
12.2 systemd 托管下手工启停导致服务 failed（完整排障实录）
现象：管理员用 mailman stop/mailman start 手工重启过服务后，systemctl is-active mailman3 显示 inactive；再执行 systemctl restart mailman3 直接失败：
Job for mailman3.service failed because the control process exited with error code.
See "systemctl status mailman3.service" and "journalctl -xeu mailman3.service" for details.
诊断：看单位状态与日志。
systemctl status mailman3 --no-pager
实测回显：
× mailman3.service - GNU Mailman 3 Core
Loaded: loaded (/etc/systemd/system/mailman3.service; enabled; vendor preset: enabled)
Active: failed (Result: exit-code) since Wed 2026-10-21 06:45:37 UTC; 17s ago
Process: 8652 ExecStart=/opt/mailman/venv/bin/mailman start (code=exited, status=2)
CPU: 538ms
Oct 21 06:45:36 list.example.org systemd[1]: Starting GNU Mailman 3 Core...
Oct 21 06:45:37 list.example.org mailman[8652]: Usage: mailman start [OPTIONS]
Oct 21 06:45:37 list.example.org mailman[8652]: Try 'mailman start --help' for help.
Oct 21 06:45:37 list.example.org mailman[8652]: Error: GNU Mailman is already running
Oct 21 06:45:37 list.example.org systemd[1]: mailman3.service: Control process exited, code=exited, status=2/INVALIDARGUMENT
Oct 21 06:45:37 list.example.org systemd[1]: mailman3.service: Failed with result 'exit-code'.
关键一行是 Error: GNU Mailman is already running——手工 mailman start 拉起的 master（新 PID）仍存活并持有锁，systemd 的 ExecStart 再跑 mailman start 自然撞锁。进一步确认进程与 PID 文件状态：
ps aux | grep -E "[m]aster -C"
实测回显：
mailman 8563 0.5 0.2 88632 78272 ? Ss 06:44 0:00 /opt/mailman/venv/bin/python3 /opt/mailman/venv/bin/master -C /etc/mailman3/mailman.cfg
ls -la /opt/mailman/var/master.pid /opt/mailman/var/locks/master.lck
实测回显：
ls: cannot access '/opt/mailman/var/master.pid': No such file or directory
-rw-rw---- 2 mailman mailman 75 Oct 22 2026 /opt/mailman/var/locks/master.lck
即：master 进程活着、锁在、但 master.pid 文件丢失——此刻连 mailman stop 都会因读不到 PID 报错（实测回显）：
PID unreadable in: /opt/mailman/var/master.pid
[Errno 2] No such file or directory: '/opt/mailman/var/master.pid'
Is the master even running?
Shutting down Mailman's master runner
解决（按序执行，每步独立验证）：
- 直接向残留的 master 进程发 TERM 信号（PID 以
ps实际输出为准）：
sudo kill 8563
- 确认进程与状态清干净：
ps aux | grep -E "[m]aster -C"
实测回显：无输出（进程已不存在）。
sudo -u mailman /opt/mailman/venv/bin/mailman status
实测回显：
GNU Mailman is not running
- 交给 systemd 正常启动：
sudo systemctl start mailman3
- 双重验证：
systemctl is-active mailman3
实测回显：
active
sudo -u mailman /opt/mailman/venv/bin/mailman status
实测回显：
GNU Mailman is running (master pid: 8698)
预防：systemd 托管的部署（mailman3.service）日常启停只走 systemctl；mailman restart/mailman reopen 不动 master 进程，与 systemd 混用安全。
12.3 mailman stop 报 PID unreadable 是什么问题？
同 12.2 节诊断段的场景：/opt/mailman/var/master.pid 文件丢失而 master 进程与锁仍在（多发生在手工启停与 systemd 交叉操作后）。先 ps aux | grep "[m]aster -C" 找到真实 PID 手工 kill，等 mailman status 显示 GNU Mailman is not running 后再由 systemd 启动。不要在 master 存活时反复执行 mailman stop，它只会重复打印同一错误。
12.4 mailman shell 里访问 m 报 AttributeError？
现象：不带 -l 进入交互 shell，直接访问 m 的属性。实测（echo 'print(m.lists)' 管道喂入）：
>>> Welcome to the GNU Mailman shell
Use commit() to commit changes.
Use abort() to discard changes since the last commit.
Exit with ctrl+D does an implicit commit() but exit() does not.
Traceback (most recent call last):
File "<console>", line 1, in <module>
AttributeError: 'NoneType' object has no attribute 'lists'
定位：不指定列表时 m 为 None，它不是系统全局对象。解决：带 -l <listspec> 启动，m 才绑定列表对象（正确用法与回显见 10.1 节）。要在无列表上下文做系统级操作，用 -r 脚本模式的不带参函数。
12.5 aliases 命令生成的文件在哪？能改吗？
默认生成到配置生效目录（本文环境为 /opt/mailman/var/data/ 下的 postfix_lmtp、postfix_domains 及其 .db 哈希文件），命令静默无输出；-d DIRECTORY 可输出到备用目录观察（目录必须先建好，见 12.6 节）。文件头已警示自动生成勿手工编辑——新增/删除列表后重跑 mailman aliases 即与 Postfix 保持同步，手改会在下次生成时被覆盖。
12.6 aliases -d 报 Directory does not exist？
现象（目标目录未创建时）：
Usage: mailman aliases [OPTIONS]
Try 'mailman aliases --help' for help.
Error: Invalid value for '--directory' / '-d': Directory '/tmp/aliasout' does not exist.
解决：先 sudo mkdir -p /tmp/aliasout && sudo chown mailman: /tmp/aliasout 再执行 -d；运行用户 mailman 对该目录必须有写权限。
12.7 gatenews 为什么直接报错？
见 9.3 节：gatenews 由 nntp runner 周期执行，手工运行被显式拒绝，错误信息里写明了解决路径（cron 移除或设置 _MAILMAN_GATENEWS_NNTP）。这不是故障，是防重复拉取的保护设计。
十三、参考链接
- 本专栏系列（部署与配置）：《Ubuntu 22.04 安装 Mailman 指南》、《Mailman 3.3.10 配置参数详解》、《Mailman 3.3.10 介绍与选型指南》
- Mailman 3 官方文档：https://docs.mailman3.org/en/latest/
- Mailman Core 官方手册（含命令行章节）：https://docs.mailman3.org/projects/mailman/en/latest/
- PyPI 项目页（版本信息，查询日期 2026-10-21）：https://pypi.org/project/mailman/
- 官方主页：https://www.list.org/
章节目录