Roundcube 1.7.5 常用 CLI 命令详解

目标：把 Roundcube 安装包 bin/ 目录下的命令行工具逐条讲透——每个脚本给用途、调用格式、真实执行回显与实测发现的坑。实测环境为 Roundcube 1.7.5（官方 Complete 包）+ Ubuntu 22.04 + MariaDB 10.6 + Dovecot/Postfix 本机邮件后端，部署过程见本专栏《Ubuntu 22.04 安装 Roundcube 1.7.5 指南》，配置项见《Roundcube 1.7.5 配置参数详解》。所有脚本统一以 php bin/<脚本名> 在 Roundcube 安装目录下运行。

1. bin/ 全景：18 个脚本按用途分类

# ls /var/www/roundcube/bin
cleandb.sh  cssshrink.sh  decrypt.sh  deluser.sh  gc.sh  healthcheck.sh  identity.sh
indexcontacts.sh  initdb.sh  installto.sh  jsshrink.sh  makedoc.sh  moduserprefs.sh
msgexport.sh  msgimport.sh  update.sh  updatecss.sh  updatedb.sh

分类	脚本	用途
健康检查	`healthcheck.sh`	检查 DB/IMAP/SMTP 三路连通性
数据库	`initdb.sh` / `updatedb.sh`	空库初始化 / 结构增量更新
升级迁移	`update.sh` / `installto.sh`	本地升级向导 / 跨目录复制升级
用户治理	`deluser.sh` / `moduserprefs.sh` / `identity.sh`	删用户 / 改用户偏好 / 管理发件身份
邮件搬运	`msgimport.sh` / `msgexport.sh`	IMAP 导入 .eml / 导出 mbox
缓存与索引	`indexcontacts.sh` / `cleandb.sh` / `gc.sh`	联系人索引 / 清理过期记录 / 回收临时目录
界面资源	`updatecss.sh`	皮肤静态资源（含 RTL/压缩）重建
安全取证	`decrypt.sh`	解密被加密的邮件头
开发辅助	`jsshrink.sh` / `cssshrink.sh` / `makedoc.sh`	前端资源压缩 / API 文档生成

2. healthcheck.sh —— 三路连通性体检

运维排障第一入口，直接输出数据库、IMAP、SMTP 的连通结论：

# cd /var/www/roundcube && php bin/healthcheck.sh
DB: OK
IMAP: OK (localhost:143)
SMTP: OK (localhost:25)

配置变更后（如换 imap_host、改 db_dsnw 密码）先跑一遍它，比登录页面报错高效得多。

3. initdb.sh / updatedb.sh —— 数据库结构的"建"与"升"

3.1 initdb.sh：空库初始化

# php bin/initdb.sh --dir SQL
Creating database schema... [OK]
# mysql roundcube -N -e "SELECT COUNT(*) FROM information_schema.tables WHERE table_schema='roundcube';"
18

--dir 必须指向包含 <驱动名>.initial.sql 的目录（即源码包的 SQL/），不是驱动子目录。两个实测错误示范：

# php bin/initdb.sh --dir SQL/mysql
ERROR: DDL file SQL/mysql/mysql.initial.sql not found
# php bin/initdb.sh --dir SQL      # 库里已有表时重复执行
Creating database schema...
...[1050] Table 'session' already exists

即：--dir 给错只报 DDL not found；对已初始化的库重跑会以 MySQL 1050 错误收场（无破坏性，但没有任何表被补建）。

3.2 updatedb.sh：结构增量更新

# php bin/updatedb.sh --dir SQL --package roundcube
# echo $?
0

库结构已是最新时静默退出、退出码 0——把它放进升级流程的固定步骤，配合退出码判断即可，不要期待它输出"nothing to do"。

4. update.sh —— 升级向导（交互式）

# printf "n\n" | php bin/update.sh
What version are you upgrading from? Type '?' if you don't know.
Executing database schema update.
This instance of Roundcube is up-to-date.
Have fun!

大版本升级的标准动作：下载新包替换 program/、skins/、public_html/ 等目录（保留 config/），跑 update.sh 完成数据库结构迁移（答 n 跳过备份交互时按提示操作）。上面回显正是"已是最新版"时的输出。它还会检查 config/ 与新版默认配置的差异并给出合并建议。

5. installto.sh —— 跨目录复制/升级（1.7.4 → 1.7.5 实测）

把当前实例（源）整体复制并升级到目标目录。目标必须已是一套 Roundcube 安装：

# php bin/installto.sh /root/no-such-rc
ERROR: Invalid target: not a directory
Usage: installto.sh [-y] <TARGET>
# php bin/installto.sh /root/rc-target
ERROR: No valid Roundcube installation found at /root/rc-target

准备一个 1.7.4 目录作为目标后实测升级：

# printf "y\n" | php bin/installto.sh /root/rc-target
Upgrading from 1.7.4. Do you want to continue? (y/N)
Copying files to target location..../
cleandb.sh
cssshrink.sh
decrypt.sh
deluser.sh
...
done.

Running update script at target...
This instance of Roundcube is not yet configured!
Open http://url-to-roundcube/installer.php in your browser and follow the instructions.
All done.
# grep -m1 RCUBE_VERSION /root/rc-target/program/lib/Roundcube/bootstrap.php
define('RCUBE_VERSION', '1.7.5');

目标目录的版本常量已从 1.7.4 变为 1.7.5——installto.sh 是多实例运维下最省事的"推升级"方式；加 -y 可跳过确认。注意目标实例需停 Web 服务或接受短暂不一致，复制完成后务必对目标跑一次 update.sh。

6. deluser.sh —— 删除用户（含 dry-run 陷阱）

# php bin/deluser.sh
Missing required parameters
Usage: deluser.sh [--host=HOST][--age=DAYS][--dry-run] [username]
--host=HOST  The IMAP hostname or IP the given user is related to
--age=DAYS   Delete all users who have not logged in for more than X days
--dry-run    List users but do not delete them (for use with --age)

按用户名删除（连带 identities、contacts、session 等关联数据）：

# php bin/deluser.sh ghost
Successfully deleted user 6
# php bin/deluser.sh ghost3
User not found.

实测陷阱：帮助文本已写明 --dry-run 只配合 --age 使用；若单独对用户名加 --dry-run，该标志被忽略、真的删了：

# mysql roundcube -N -e "SELECT COUNT(*) FROM users WHERE username='ghost3';"
1
# php bin/deluser.sh --dry-run ghost3
Successfully deleted user 2
# mysql roundcube -N -e "SELECT COUNT(*) FROM users WHERE username='ghost3';"
0

想安全演练请用 --age=N 配合 --dry-run（列出超 N 天未登录用户但不删除），或先在测试库操作。

7. moduserprefs.sh —— 批量改用户偏好

# php bin/moduserprefs.sh
Usage: moduserprefs.sh [options] pref-name [pref-value]
Options:
    --user=user-id User ID in local database
    --config=path  Location of additional configuration file
    --delete       Unset the given preference
    --type=type    Pref-value type: int, bool, string

改某个用户的偏好（以时区为例，写入 users.preferences 的序列化数据）：

# php bin/moduserprefs.sh --user=5 --type=string timezone "Europe/Berlin"
Updating prefs for user 5...saved.
# mysql roundcube -N -e "SELECT preferences FROM users WHERE user_id=5;" | grep -o 'timezone";s:13:"[^"]*'
timezone";s:13:"Europe/Berlin"
# php bin/moduserprefs.sh --user=5 --delete message_sort_col
Updating prefs for user 5...saved.

适用场景：全站统一改某个偏好（不带 --user 则作用于所有用户）、删除污染的偏好键。参数值直接写进序列化 blob，--type 与值类型不符会造成会话数据异常，操作前备份 users 表。

8. identity.sh —— 发件身份管理

# php bin/identity.sh
Available sub-commands:
add       - create a new identity for a user
delete    - delete an identity (mark as deleted)
list      - list all identities of a user
get-attr  - get some attribute of an identity
update    - update identity
# php bin/identity.sh add -u admin -e admin@example.local -n "Administrator"
Identity created successfully with ID: 6.
# php bin/identity.sh list -u admin
identity_id      : 1
user_id          : 3
changed          : 2026-10-21 03:50:47
del              : 0
standard         : 1
name             : admin
organization     :
email            : admin@localhost
reply-to         :
bcc              :
signature        :
html_signature   : 0
email_ascii      : admin@localhost
ident            : admin <admin@localhost>

用户首次登录时 Roundcube 会自动创建默认身份（上例 identity_id 1，邮箱为 用户名@mail_domain缺省主机名）。可以用 add 补充别名身份、update 改签名、delete 软删（del 字段置 1）——脚本化开通用户时非常有用。

9. msgimport.sh / msgexport.sh —— 邮件导入导出

9.1 导入 .eml 到 IMAP 邮箱

# php bin/msgimport.sh
Usage: msgimport.sh -h imap-host -u user-name -m mailbox -f message-file
--host   IMAP host
--user   IMAP user name
--mbox   Target mailbox
--file   Message file to upload
# echo q1w2e3r4 | php bin/msgimport.sh -h localhost -u admin -m INBOX -f /root/cli-test.eml
IMAP login successful.
Uploading messages...
1 messages successfully added to INBOX.
# doveadm search -u admin mailbox INBOX ALL | wc -l
2

密码通过交互提示输入（脚本式调用可从 stdin 喂入，如上）。验证：doveadm search 显示 INBOX 从 1 封变 2 封。批量迁移老邮件归档时按文件循环调用即可。

9.2 导出 mbox

# echo q1w2e3r4 | php bin/msgexport.sh -h localhost -u admin -m INBOX > /root/export.mbox
Getting message list of INBOX... 3 messages
100% [==================================================>] 3/3
complete.
# ls -l /root/export.mbox
-rw-r--r-- 1 root root 1339 Oct 21 03:58 /root/export.mbox
# grep -c "^From " /root/export.mbox
3

标准 mbox 格式落盘，可被 formail/procmail/其他邮件工具消费。两件套构成了"不进浏览器也能搬运邮件"的通道。

10. indexcontacts.sh / cleandb.sh / gc.sh —— 索引与清理

# php bin/indexcontacts.sh
Indexing contacts for user 3...
done.
# php bin/cleandb.sh
0 records deleted from 'contacts'
0 records deleted from 'contactgroups'
0 records deleted from 'identities'
0 records deleted from 'responses'
# php bin/gc.sh
# echo $?
0

indexcontacts.sh：重建联系人搜索索引（升级后首次跑一次，或搜索异常时手动触发）；
cleandb.sh：清除已删除用户的残留关联记录（软删用户的数据归零清理），实测为静默型输出逐表报数；
gc.sh：回收 temp/ 临时文件与过期缓存，正常执行无输出、退出码 0。

三者都适合放进 cron（见第 13 节）。

11. updatecss.sh —— 皮肤静态资源重建

# php bin/updatecss.sh
Skin directory not specified (--dir). Using skins/ and plugins/*/skins/.
Image: /var/www/roundcube/skins/elastic/images/favicon.ico (924a.16958)
File: /var/www/roundcube/skins/elastic/watermark.html
File: /var/www/roundcube/skins/elastic/templates/compose.html
File: /var/www/roundcube/skins/elastic/templates/dialog.html
...

替换或修改皮肤文件后运行，重写带版本指纹的引用、生成 RTL 与压缩变体。自定义皮肤部署的标准收尾步骤。

12. decrypt.sh —— 加密邮件头取证

# php bin/decrypt.sh
Usage: decrypt.sh encrypted-hdr-part [encrypted-hdr-part ...]

Roundcube 会对部分敏感邮件头（如_SUBJECT_加密头）做 des_key 加密存储；把密文片段传给它即可还原，用于排查"邮件列表里标题显示为密文"的问题。注意它同样依赖 config.inc.php 中的 des_key——换过密钥的历史密文无法解出。

13. 开发辅助脚本与定时任务

jsshrink.sh / cssshrink.sh 压缩 JS/CSS（依赖_closure_compiler_等外部工具，日常部署用不到）；makedoc.sh 生成 API 文档（依赖 phpdoc 环境）。这三者属于构建期工具，生产服务器无需关注。

cron 定时清理建议：

# 每日凌晨 3:40 回收临时目录并清理过期记录
40 3 * * * cd /var/www/roundcube && php bin/gc.sh   >/dev/null 2>&1
50 3 * * 0 cd /var/www/roundcube && php bin/cleandb.sh >/dev/null 2>&1

14. 常见问题

Q1：脚本一跑就报 "ERROR: Loading configuration from ..."？ 多为 config.inc.php 语法错误或 db_dsnw 连不上——先 php -l config/config.inc.php，再 php bin/healthcheck.sh 看 DB 一行。

Q2：msgimport/msgexport 提示 IMAP login failed？ 密码是交互提示输入的，非交互环境要从 stdin 提供；-h 要与 imap_host 一致（本机测试用 localhost）。

Q3：installto.sh 说 "No valid Roundcube installation found"？ 目标目录必须已有 program/include/iniset.php 等 Roundcube 结构（它校验的是"一套可识别的安装"），全新目录请直接解压官方包。

Q4：deluser.sh 的 --dry-run 到底删不删？ 单独对用户名使用时不生效、会真删（帮助文本写明 "for use with --age"）；安全演练用 --age=DAYS --dry-run 组合。

参考资料

Roundcube 1.7.5 Complete 包内 bin/ 脚本源码（各脚本头部 Usage 注释）
本站相关文档：Ubuntu 22.04 安装 Roundcube 1.7.5 指南、Roundcube 1.7.5 配置参数详解、Dovecot 2.3.16 进阶实战与运维