Sympa 6.2.80 CLI 命令详解

目标：覆盖 sympa CLI 全部子命令（24 个，官方 man page sympa(1)），按 6 个功能组讲解语法、高频场景、与 6.2.66 旧版长选项语法的对照。所有命令定义出自官方 sympa(1) man page（2026-10-27 读取），B1 实测 6.2.66 环境中的命令作为新旧对照。组件背景见《Sympa 6.2.80 介绍与选型指南》，安装实测见《Sympa 6.2.66 Ubuntu 22.04 安装指南》，配置参数见《Sympa 配置参数详解》。

一、CLI 体系概述

1.1 演进脉络

Sympa 命令行管理入口经历了两次形态演进：

版本	入口	语法	示例
6.2a.4 前	`sympa.pl`	单一程序 + 批量模式长选项	`sympa.pl --add_list=family --robot=dom --input_file=file.xml`
6.2a.4 – 6.2.67	`sympa.pl`	长选项批量 + 新 CLI 雏形并存	同上，同时 `sympa.pl --add_list` 改名叫 `sympa create`
6.2.68+（当前）	`sympa`	子命令风格	`sympa create list --input_file=file.xml robot_name`

B1 实测的 6.2.66（jammy 包）仍用长选项（sympa.pl --create_list --robot=...）；上游 6.2.80 已全量迁到子命令风格。混用资料时先对版本号。

Debian 包路径：

6.2.66：/usr/lib/sympa/bin/sympa.pl
6.2.80（源码安装）：$prefix/bin/sympa

1.2 调用格式

sympa <command> [--general-option ...] [--command-option ...] <target>

通用选项（所有子命令前都能加）：

选项	缩写	说明
`--debug`	`-d`	开启调试输出（verbose）
`--config=<file>`	`-f`	强制用替代 sympa.conf 而非 `/etc/sympa/sympa/sympa.conf`
`--lang=<lang>`	`-l`	指定语言，catalog 位于 `$LOCALEDIR`
`--log_level=<level>`	—	设 sympa 日志级别（0-3）
`--mail`	`-m`	开启 SMTP 级日志（投递排障用）
`--noout`	—	跳过控制台输出，仅 fatal error（6.2.71b+）

1.3 目标定位语法

多数命令的末尾是「目标」——一个或多个列表/域/家族，格式：

list@domain          # 单列表
family@@domain       # 整个家族（双 @）
"*"                  # 所有列表
"list*"              # glob 通配所有匹配列表

新旧对照：6.2.67 以前用 --robot=domain + --family=family 长选项分别传；6.2.68+ 统一到末尾位置参数。

二、子命令详解

2.1 列表生命周期

`sympa create list` — 创建列表

sympa create list --input_file=<xml> <robot_name>
sympa create --input_file=<xml> <family>@@<robot_name>   # 家族式批量

核心参数：

--input_file：XML 描述文件，最小字段 <listname> <subject> <topics> <owner>（B1 实测样例见下）
<robot_name>：该列表所属的虚拟域（robot 名）

XML 模板最小样例（B1 实测通过）：

<list>
  <listname>team-test</listname>
  <type>discussion_list</type>
  <subject>Team Test List</subject>
  <topics>computers</topics>
  <owner multiple="1">
    <email>listmaster@sympa-apt.test.example.org</email>
  </owner>
</list>

实测回显：List "team-test" has been created. 同时 alias_manager.pl 写列表别名到 sendmail_aliases 指定文件、sympa 新列表目录 /var/lib/sympa/list_data/<list>@<robot>/ 初始化。

6.2.66 旧版对照：

# B1 实测（6.2.66 jammy 包）
sympa.pl --create_list --robot=sympa-apt.test.example.org --input_file=/tmp/list.xml

`sympa close` — 关列表

sympa close <list>[@<robot>]           # 关列表（status→closed，保留数据）
sympa close --mode=purge <list>[@<robot>]  # 彻底删除（归档、配置、成员全清，不可恢复）
sympa close <family>@@<robot>          # 关整个家族

close 后：sympa 从 DB 中删除订阅者（自动 dump 到 list 目录备恢复）、重建别名、列表地址发信全 bounce。

`sympa open` — 重开已关闭列表

sympa open [--notify] <list>[@<robot>]

从 dump 文件恢复成员、重建别名、--notify 给 owner 发通知。

`sympa move` / `sympa copy` — 列表迁移

sympa move <old_list>@<robot> <new_list>@<new_robot>    # 改名 + 跨域移动
sympa move --mode=copy <old>@<robot> <new>@<robot>     # 复制（原列表不动）
sympa copy <old_list>@<robot> <new_list>@<robot>       # copy 是 move --mode=copy 别名

`sympa update` — 更新家族式列表

sympa update --input_file=<xml> <family>@@<robot>

对应家族模板中的列表结构变更（如家族定义新增列表）。

`sympa instantiate` — 实例化家族模板

sympa instantiate --input_file=<xml> [--close_unknown] [--quiet] <family>@@<robot>

sympa_automatic.pl 的手动等价——按 XML 描述批量建列表，--close_unknown 把 XML 中没列的同家族现有列表关掉。

2.2 成员管理

`sympa add` — 加订阅者

sympa add [--role=<role>] [--quiet] [--notify] [--force] <list>@<domain>
# 从 stdin 读每行一个订阅者：address<TAB>name
printf "root@host\tRoot\nuser@host\tUser\n" | sympa add team@domain

--role 可选 member（默认）/ owner / editor，可逗号分隔。B1 实测用 --import（旧版，已废弃）导入，对应 6.2.80 的 sympa add。

`sympa del` — 删订阅者

sympa del [--role=<role>] [--quiet] [--notify] [--force] <list>@<domain>
# 从 stdin 读删除地址
printf "user@host\n" | sympa del team@domain

`sympa review` — 列出成员

sympa review <list>@<domain>

返回成员表（地址、角色、加入时间、状态），可 --roles=<roles> 过滤只看 owner/editor。

`sympa dump` — 导出成员到文件

sympa dump [--roles=<roles>] <list>@<domain>   # 单列表
sympa dump [--roles=<roles>] "*"               # 所有列表

每个列表目录下生成 member.dump / owner.dump / editor.dump。

`sympa restore` — 从 dump 恢复成员

sympa restore [--roles=<roles>] <list>@<domain>
sympa restore [--roles=<roles>] "*"

`sympa user` — 用户管理（二级子命令）

sympa user move <current_email> <new_email>    # 跨所有列表/表改邮箱
sympa user ...                                 # 其他二级子命令见 help user

`sympa bouncers` — 退信用户操作

sympa bouncers ...    # 处理 bounced.pl 标记的成员，见 help bouncers

`sympa set` — 设置成员属性

sympa set ...    # 设成员的订阅/不订阅/摘要、默认邮箱频率等

2.3 配置与健康检查

`sympa check` — 环境自检

sympa check

检查 sympa.conf / 各 robot.conf / 数据库表结构。有问题 exit code 非 0，生产巡检建议加 cron 周期跑。6.2.66 旧版：sympa.pl --health_check。

`sympa config` — 配置文件操作

sympa config ...    # 读写 sympa.conf / robot.conf 的简单接口，详见 help config

`sympa reload_list_config` — 刷配置缓存

sympa reload_list_config                     # 全列表
sympa reload_list_config --list=<list>@<domain>   # 单列表
sympa reload_list_config --robot=<domain>           # 单域

改了 scenario 或 list config 后必须调用——所有列表的 config.bin 缓存要重建，否则 sympa_msg.pl 继续用旧缓存。

`sympa sync_list_db` — 同步列表配置到 DB 缓存

sympa sync_list_db [--list=<list>@<domain>]

把文件系统上的 list config 同步进 database list_table 的 config_cache 字段。

`sympa upgrade` — 版本升级

sympa upgrade [--from=<X>] [--to=<Y>]    # 跨版本 DB schema 迁移
sympa upgrade ... shared                  # 重命名 shared/ 目录文件
sympa upgrade password                   # 废弃密码重编码（原 --md5_encode_password）

跨主版本（如 5→6.2）升级时的必跑脚本，内部会对比 DB schema、迁移数据结构、改 token/session 表字段。

2.4 周期/归档

`sympa rebuildarc` — 重建归档

sympa rebuildarc <list>[@<robot>]

内建归档器把 spool/arc 或数据库里的归档重新生成 HTML 归档目录。列表归档损坏或升级归档器后必跑。

`sympa include` — 触发外部数据源同步

sympa include [--role=<role>] <list>@<robot>

当列表成员由 LDAP/DB/远程文件数据源驱动时，include 触发 sympa_msg.pl 立即重新拉取成员列表。6.2.66 旧版：sympa.pl --sync_include。

`sympa send_digest` — 立即发摘要

sympa send_digest [--keep_digest]    # --keep_digest 发完不删队列里的 digest

摘要通常由 task_manager.pl 定时发（按列表 config 里 digest=weekly 等），此命令强制立即触发，调试/运维用。

`sympa make_alias_file` — 生成临时别名文件

sympa make_alias_file [--robot=<domain>]

用 list_aliases.tt2 模板生成完整别名文件到 /tmp/，改了别名模板后验证输出用。

`sympa lowercase` — DB 邮箱地址小写化

sympa lowercase

把 DB 里所有 email 地址转小写（DNS 邮箱域不区分大小写，大小写混用可能导致重复订阅者）。一次性修复脚本。

2.5 SOAP 辅助 / 杂项

`sympa md5_digest` — 生成密码摘要

sympa md5_digest <password>    # 输出 MD5 哈希

SOAP API trusted_applications.conf 里配置可信应用时，密码字段存的是 md5_digest 而非明文——此命令生成摘要。

`sympa show_pending_lists` — 列待审批列表

sympa show_pending_lists <robot>

新列表创建后若走审批流（scenario automatic_list_creation.* 设了 owner/review 审批），此命令列出所有 status=pending 的列表。

`sympa test` — 功能测试

sympa test ...    # 触发 Sympa 内建的诊断测试（收信/投递/归档全链路）

`sympa version` — 版本号

sympa version

实测回显：Sympa 6.2.80 / Sympa 6.2.66，与源码 configure.ac AC_INIT 或 Debian 包版本一致。

`sympa help [command]` — 查看帮助

sympa help          # 全部子命令列表
sympa help create   # create 子命令详细语法

三、新旧语法对照表

以下高频操作的长选项（6.2.67 及以前）与子命令（6.2.68+）完整映射，来自 sympa(1) man page "DESCRIPTION FOR EARLIER VERSION" 节和 B1 实测：

功能	6.2.67 长选项（B1 实测）	6.2.68+ 子命令
建列表	`sympa.pl --create_list --robot=dom --input_file=file.xml`	`sympa create list --input_file=file.xml dom`
加成员	`sympa.pl --add=list@dom`（stdin 输入，6.2.67b+）	`sympa add list@dom`（stdin）
删成员	`sympa.pl --del=list@dom`（stdin 输入，6.2.67b+）	`sympa del list@dom`（stdin）
导出成员	`sympa.pl --dump_users --list=list@dom --role=member`	`sympa dump --roles=member list@dom`
恢复成员	`sympa.pl --restore_users --list=list@dom`	`sympa restore list@dom`
关列表	`sympa.pl --close_list=list@dom`	`sympa close list@dom`
重开列表	`sympa.pl --open_list=list@dom`	`sympa open --notify list@dom`
改名/移动	`sympa.pl --rename_list=old@dom --new_listname=new --new_listrobot=newdom`	`sympa move old@dom new@newdom`
清理（purge）	`sympa.pl --purge_list=list@dom`	`sympa close --mode=purge list@dom`
健康检查	`sympa.pl --health_check`	`sympa check`
家族实例化	`sympa.pl --instantiate_family=family --robot=dom --input_file=file.xml`	`sympa instantiate --input_file=file.xml family@@dom`
同步外部数据源	`sympa.pl --sync_include=list@dom`	`sympa include list@dom`
版本升级	`sympa.pl --upgrade`	`sympa upgrade`
密码重编码	`sympa.pl --md5_encode_password`（废弃）	`sympa upgrade password`

⚠️ B1 实测：6.2.66（jammy 包）用长选项 --create_list；源码安装的 6.2.80 用子命令 sympa create list。混用旧版 man page（写着 --add=...）和新版 sympa 二进制（只认 sympa add）最容易出问题——执行前先跑 sympa help 看当前版本支持的语法。

四、SOAP API 简述

Sympa 6.2 时代的管理 API 走 SOAP/XML（源码 src/cgi/sympa_soap_server.fcgi + 配套 sympa.wsdl），与 Mailman 3 的 REST 风格不同。CLI 仍是自动化的主力，SOAP 适合需要结构化返回、已在 WSDL 中绑定的第三方语言（Java/C#/Python zeep）。

4.1 启用条件

sympa.conf 必须配 soap_url，Web 服务器（nginx/Apache）把 soap_url 路径代理到 FastCGI 进程 sympa_soap_server.fcgi，Debian 包已经在 /lib/systemd/system/sympasoap.socket + sympasoap.service 里封装好了。

4.2 可信应用

SOAP 调用方需要在 trusted_applications.conf 里注册（6.2.68+ 支持 Web 管理端登记），密码字段用 sympa md5_digest 生成摘要，明文不入库。

4.3 核心方法（WSDL 中暴露）

方法	等价 CLI	说明
`createList`	`sympa create list`	参数：listname, subject, template, description, topic（均必填）
`addMembers`	`sympa add`	批量加订阅者
`delMembers`	`sympa del`	批量删订阅者
`reviewList`	`sympa review`	返回成员列表（结构化 XML）
`closeList`	`sympa close`	关列表
`listLists`	`sympa show_pending_lists` + 已建列表查询	按 robot 查现有列表

SOAP API 完整方法列表见源码 default/sympa.wsdl（700+ 行）和官方 SOAP API 文档。

4.4 何时选 SOAP vs CLI

场景	推荐
Shell 脚本/Ansible/运维	CLI（sympa 子命令，bash 友好）
Python 一次性脚本	CLI（`subprocess` 调 sympa 命令，解析 stdout）
需要结构化成员表/列表列表（JSON/XML）	SOAP（CLI stdout 是纯文本表格，解析困难）
多语言绑定（Java/C#/.NET）	SOAP（zeep/wsimport 直接从 WSDL 生成客户端）
已用 sympa 6.2.68+	CLI（子命令风格更统一）
还在用 6.2.67 或更早	CLI（长选项风格），SOAP 不受版本演进影响

💡 sympa 社区已明确 REST API 是 6.3 开发线方向（见选型篇「Sympa 自身替代考量」节），6.2 时代生产选 CLI 为主、SOAP 为辅即覆盖全部管理面。

五、FAQ

sympa create list 报 Matching topic not found：XML <topics> 值必须在 /etc/sympa/topics.conf 里已定义；grep -E "^[a-z]" /etc/sympa/topics.conf 查可用值（B1 实测 computers 可用）。
调 sympa add 但订阅者没进 DB：先 sympa check 看 DB 连接；再确认 sympa_msg.pl 运行中（systemctl is-active sympa.service），CLI 加成员需要 sympa_msg.pl 从 queueauth spool 消费授权请求。
sympa reload_list_config 改了 scenario 后没生效：确认 sympa_msg.pl 没在吃旧的 config.bin；systemctl restart sympa.service 强制拉新。
SOAP 调用返回 500：先确认 sympasoap.socket 和 sympasoap.service 都是 active，curl -s http://127.0.0.1/$(soap_url 路径) | head -c 200 看 FastCGI 进程是否响应。
6.2.66 的 --import 哪去了：已废弃，6.2.80 用 sympa add 从 stdin 导入（格式完全相同）。
sympa version 输出不是预期版本号：Debian 包可能同时装了源码版——查 which sympa vs which sympa.pl 用的哪个。

六、参考链接

官方 sympa(1) man page（在线版）：https://www.sympa.community/gpldoc/man/sympa.1.html（本文主要来源）
官方 SOAP API 文档：https://www.sympa.community/manual/customize/soap-api.html
源码 sympa.wsdl（SOAP 接口定义）：/opt/data/quzuo/tmp/sympa/src/default/sympa.wsdl
B1 安装指南（6.2.66 长选项实测、建列表闭环）：《Sympa 6.2.66 Ubuntu 22.04 安装指南》
C1 配置参数（sympa_url/trusted_applications.conf）：《Sympa 配置参数详解》
选型篇（SOAP vs REST vs CLI 对比）：《Sympa 6.2.80 介绍与选型指南》

Sympa CLI 命令详解

Sympa 6.2.80 CLI 命令详解

一、CLI 体系概述

1.1 演进脉络

1.2 调用格式

1.3 目标定位语法

二、子命令详解

2.1 列表生命周期

sympa create list — 创建列表

sympa close — 关列表

sympa open — 重开已关闭列表

sympa move / sympa copy — 列表迁移

sympa update — 更新家族式列表

sympa instantiate — 实例化家族模板

2.2 成员管理

sympa add — 加订阅者

sympa del — 删订阅者

sympa review — 列出成员

sympa dump — 导出成员到文件

sympa restore — 从 dump 恢复成员

sympa user — 用户管理（二级子命令）

sympa bouncers — 退信用户操作

sympa set — 设置成员属性