Cyrus IMAP 3.4 常用 CLI 命令详解

目标：系统讲解 Cyrus IMAP 3.4 的管理命令族——cyradm 邮箱管理 Shell、cyrus 包装器、ctl_mboxlist/reconstruct/quota/mbpath 等维护工具，每条命令均附实测输入与回显。基于 Ubuntu 22.04 官方仓库 3.4.3 环境。

一、环境信息

服务器：Ubuntu 22.04.5 LTS，主机名 mail.example.com
软件：cyrus-imapd 3.4.3-3ubuntu0.3 + cyrus-admin + cyrus-clients（安装见《Ubuntu 22.04 安装 Cyrus IMAP 3.4 指南》）
命令位置：管理工具统一在 /usr/lib/cyrus/bin/（不在默认 PATH），包装器 /usr/sbin/cyrus
演示账号：管理员 cyrus、业务用户 admin，密码 q1w2e3r4；示例邮箱 user.admin（含 1 封测试信）
维护类命令需以 cyrus 身份执行：su -s /bin/bash cyrus -c "<命令>"

二、工具概览

Cyrus 命令面分三类（ls /usr/lib/cyrus/bin/ 实测共 50+ 个二进制）：

类别	命令	用途
交互管理	cyradm	邮箱/ACL/配额的一站式管理 Shell（走 IMAP 协议）
包装器	cyrus <子命令>	统一入口，等价于直接调 /usr/lib/cyrus/bin/<子命令>
维护工具	reconstruct、quota、ctl_mboxlist、ctl_cyrusdb、mbpath、mbexamine、ipurge、arbitron、cyr_df、cyr_info、cyr_buildinfo、cvt_cyrusdb、unexpunge	直读直写存储与元数据库
测试客户端	imtest、pop3test、sivtest、lmtptest	协议级连通与认证验证
投递	deliver（cyrdeliver）	命令行直投邮件到邮箱

不带参数运行包装器可看到官方推荐的最常用子命令：

/usr/sbin/cyrus

usage: cyrus COMMAND [ARGS]

The most commonly used cyr commands are:
   reconstruct   reconstruct mailboxes
   quota         report and optionally fix quota usage
   squatter      reindex mailboxes
   mbpath        translate mailbox names to filesystem paths
   mboxlist      perform operations on the mailbox list database
   check         perform a consistency check of the cyrus mailstore
   tls_prune     prune expired sessions from the TLS sessions database
   ctl_cyrusdb   perform operations common to all Cyrus databases
   expire        expire messages and duplicate delivery database entries
   arbitron      arbitron mailboxes
   cvt_cyrusdb   convert a database file between cyrus database formats
   ipurge        delete mail from IMAP mailbox or partition based on age or size
   makedirs      Sets up the Cyrus IMAPd system directories (spools)

三、前置条件

服务已运行且管理员可登录：

systemctl is-active cyrus-imapd
/usr/lib/cyrus/bin/imtest -m login -u cyrus -a cyrus -w q1w2e3r4 localhost

回显含 User logged in 即可继续。

四、cyradm：邮箱管理 Shell

cyradm 是交互式管理 Shell（Perl 编写，底层走 IMAP 管理命令），进入方式：

cyradm --user cyrus --auth login localhost

IMAP Password:
localhost>

4.1 命令清单

进入后输入 help 看全部子命令（实测节选）：

createmailbox, create, cm         create mailbox
deletemailbox, delete, dm         delete mailbox
listmailbox, lm                   list mailboxes
renamemailbox, renm, rename       rename (and optionally relocate) mailbox
setaclmailbox, sam, setacl        set ACLs on mailbox
listacl, lam                      list ACLs on mailbox
setquota, sq                      set quota on mailbox or resource
listquota, lq                     list quotas on specified root
xfermailbox, xfer                 transfer (relocate) a mailbox to a different server
info / getmetadata / setmetadata  服务器与邮箱元数据
version, ver                      display version info of current server

4.2 建邮箱、查列表

localhost> cm user.admin
localhost> lm
user.admin (\HasNoChildren)

cm 建邮箱（管理员代建用户邮箱是 Cyrus 的标准姿势）；lm 列表，(\HasNoChildren) 是 IMAP 邮箱属性标记。默认层级分隔符是 .，子邮箱写作 user.admin.Sent。

4.3 改名与删除（含延迟删除行为）

localhost> cm user.admin.Archive
localhost> renm user.admin.Archive user.admin.Archives
localhost> lm
user.admin (\HasChildren)             user.admin.Archives (\HasNoChildren)

删除前必须先给管理员授权（c 删除权限位），否则 dm 静默不生效：

localhost> sam user.admin.Archives cyrus all
localhost> dm user.admin.Archives
localhost> lm
DELETED.user.admin.Archives.6ADD8784 (\HasNoChildren)
user.admin (\HasNoChildren)

⚠️ 注意：删除的邮箱被改名进 DELETED.* 命名空间而非立即抹除——这是 3.4 的延迟删除（delayed delete）机制，由 cyrus.conf EVENTS 段的 deleteprune（默认每日 04:30 清理 28 天前）最终回收，误删有挽回窗口。

4.4 ACL 权限

localhost> sam user.admin cyrus all
localhost> lam user.admin
admin lrswipkxtecdan
cyrus all

权限位速查（lrswipkxtecdan 逐字母含义）：

位	含义	位	含义
l	可见（查找）	i	追加投递
r	读取	p	转发（注入）
s	保留已读状态	k	建子邮箱
w	写标记	x	删除邮箱
t	删邮件	e	执行(expunge)
c	建/删邮箱	d	删除元数据
a	管理 ACL	n	写共享批注

4.5 配额

localhost> sq user.admin STORAGE 102400
localhost> lq user.admin
 STORAGE 0/102400 (0%)

sq 设配额（KB 单位，资源类型可 STORAGE/MESSAGE 等）；lq 查看用量/上限/百分比。

五、邮箱列表数据库：ctl_mboxlist

mailboxes.db 是全局邮箱目录（skiplist 格式），导出可读文本：

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/ctl_mboxlist -d"

user.admin	0 default admin	lrswipkxtecdan

字段含义：邮箱名、类型标志、所在分区、ACL。批量迁移/备份前导出此清单是标准动作（导入用 ctl_mboxlist -u < 文件，会打断服务，维护窗口执行）。

六、邮箱修复与体检

6.1 reconstruct 重建索引

索引（cyrus.index）与邮件文件不一致时（如磁盘故障后手工恢复文件）重建：

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/reconstruct -r -f user.admin"

user.admin

-r 递归子邮箱，-f 顺手把磁盘上存在但未登记进索引的邮件收编。输出列出处理过的邮箱名。

6.2 mbexamine 查看索引细节

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/mbexamine user.admin"

Examining user.admin... Mailbox Header Info:
  Path to mailbox: /var/spool/cyrus/mail/a/user/admin
  Mailbox ACL: admin	lrswipkxtecdan
  Unique ID: aemb6fkjp2gw1755zkhjfmbp

 Index Header Info:
  Generation Number: 0
  Minor Version: 17
  Number of Messages: 1  Mailbox Size: 536 bytes  Annotations Size: 0 bytes
  UIDValidity: 1792901829  Last UID: 1
  Deleted: 0  Answered: 0  Flagged: 0
  Mailbox Options: POP3_NEW_UIDL
  Highest Mod Sequence: 2

 Message Info:
000001> UID:00000001   INT_DATE:1792901902 SENTDATE:1792886400 SAVEDATE:1792901902 SIZE:536

排障「客户端看到的邮件数不对」时，这里是最直接的比对依据。

6.3 unexpunge 找回已 expunge 的邮件

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/unexpunge -l user.admin"

（本例邮箱无待恢复邮件，无输出行。）-l 只列出，确认后用 unexpunge -u <UID> 恢复。

七、配额与空间统计

7.1 quota 配额报告/修复

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/quota"

   Quota   % Used     Used             Resource Root
  102400        0        0              STORAGE user.admin
                         1              MESSAGE user.admin
                         0 X-ANNOTATION-STORAGE user.admin
                         1        X-NUM-FOLDERS user.admin

quota -f 可修复计数漂移的配额用量（重建索引后偶发计数漂移时用）。

7.2 cyr_df 分区空间

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/cyr_df"

Partition       1k-blocks         Used    Available Use% Location
default         308518720     52502712    240271140  18% /var/spool/cyrus/mail
news            308518720     52502712    240271140  18% /var/spool/cyrus/news

八、投递与清理

8.1 deliver 命令行投信

printf "From: admin@mail.example.com\r\nTo: admin@mail.example.com\r\nSubject: Cyrus 实测首封邮件\r\n\r\nHello Cyrus IMAP 3.4!\r\n" \
  | /usr/lib/cyrus/bin/deliver -a admin admin

（无输出即成功。）deliver 绕过 LMTP 直接落库，常用于脚本注信与 MTA 联调自测。投递后邮件文件出现在 /var/spool/cyrus/mail/a/user/admin/1.。

8.2 ipurge 按龄清理

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/ipurge -f -d 30 user.admin"

Total messages    	 1
Total bytes       	 536
Deleted messages  	 0
Deleted bytes    	 0
Remaining messages	 1
Remaining bytes   	 536

-d 30 删 30 天前的邮件（本例邮件不足 30 天，故删除 0 封）；-f 强制跳过确认。适合做垃圾箱/归档目录的定期清理（可挂 cron）。

8.3 arbitron 读者统计

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/arbitron user.admin"

Loading Mailboxes...Done
Loading Users..........................Done

有读者时会逐行输出 用户名最近阅读时间，用于盘点僵尸邮箱。

九、数据库维护与信息工具

9.1 ctl_cyrusdb 检查点

su -s /bin/bash cyrus -c "/usr/sbin/cyrus ctl_cyrusdb -c"

立即触发一次数据库检查点（正常由 cyrus.conf EVENTS 每 30 分钟自动跑）。-r 是恢复模式（master 启动时 START 段自动执行）。

9.2 cvt_cyrusdb 格式转换/导出

su -s /bin/bash cyrus -c "/usr/lib/cyrus/bin/cvt_cyrusdb /var/lib/cyrus/mailboxes.db skiplist /tmp/mbox.txt flat"

Converting from /var/lib/cyrus/mailboxes.db (skiplist) to /tmp/mbox.txt (flat)

head -2 /tmp/mbox.txt

$RUNQ	1
$RUNQ$aemb6fkjp2gw1755zkhjfmbp$user.admin

跨版本升级或换库格式（skiplist↔twoskip↔flat）时用；也是把二进制元数据库导出审计的手段。

9.3 cyr_info / cyr_buildinfo

/usr/lib/cyrus/bin/cyr_info conf        # 归一化后的全部生效配置
/usr/lib/cyrus/bin/cyr_buildinfo        # 编译组件开关（JSON）

cyr_buildinfo 输出 JSON，可见本构建开启了 murder: true、replication: true、jmap: true、sieve: true、backup: true，未启用 objectstore/kerberos_v4——判断「当前安装包是否支持某能力」以此为准。

十、测试客户端 imtest

协议级验证的瑞士军刀（配置篇的 TLS/SASL 加固全靠它取证）：

/usr/lib/cyrus/bin/imtest -m login -u cyrus -a cyrus -w q1w2e3r4 localhost   # 143 明文
/usr/lib/cyrus/bin/imtest -s -m login -u admin -a admin -w q1w2e3r4 localhost  # 993 TLS
/usr/lib/cyrus/bin/imtest -t "" -m login -u admin -a admin -w q1w2e3r4 localhost  # 143 STARTTLS

关键参数：-m 指定 SASL 机制、-s 全程 TLS、-t "" 先连后 STARTTLS 升级、-u/-a 认证身份/授权身份。banner 中的 CAPABILITY/LOGINDISABLED 是判断服务端安全策略的第一手证据。同族还有 pop3test（POP3）、sivtest（ManageSieve）、lmtptest（LMTP）。

十一、注意事项

身份隔离：reconstruct/quota/ctl_* 等直读写数据库的工具必须以 cyrus 用户运行（su -s /bin/bash cyrus -c），root 直接跑会产生属主错乱；
在线安全：cyradm 走 IMAP 协议，服务运行时可随时用；ctl_mboxlist -u（导入）、cvt_cyrusdb 原格式转换等属于维护窗口操作；
路径意识：命令都在 /usr/lib/cyrus/bin/，写监控/cron 脚本时用全路径；
延迟删除窗口：dm 删掉的邮箱在 DELETED.* 里躺到 deleteprune 到期，期间可从 cyradm 捞回，例如 renm DELETED.user.admin.Archives.6ADD8784 user.admin.Archives。

十二、常见问题（FAQ）

Q1：cyradm 提示 command not found？ 安装 cyrus-admin 包；cyradm 在 PATH 里，但它操作的维护工具多在 /usr/lib/cyrus/bin/。

Q2：cyradm 里 dm 删不掉邮箱、无任何报错？ 管理员对该邮箱缺 c 权限位，先 sam <邮箱> cyrus all 再删（见 4.3 实测）。

Q3：reconstruct 报权限拒绝？ 用 root 跑了。一律 su -s /bin/bash cyrus -c "..."。

Q4：怎么确认某邮箱在磁盘哪？ mbpath user.admin → /var/spool/cyrus/mail/a/user/admin（hashimapspool 散列子目录）。

Q5：想批量看所有用户配额？ quota 不带参数即全量报告（7.1）；结合 ctl_mboxlist -d 可对全站邮箱做巡检脚本。

十三、参考链接

Cyrus 3.4 管理命令手册索引：https://www.cyrusimap.org/3.4/imap/reference/manpages/systemcommands.html
cyradm 手册：https://www.cyrusimap.org/3.4/imap/reference/manpages/usercommands/cyradm.html
专栏导览：《Cyrus IMAP 3 介绍与选型指南》、《Ubuntu 22.04 安装 Cyrus IMAP 3.4 指南》、《Cyrus IMAP 3.4 配置参数详解》