Virtualmin 8.3.0 常用 CLI 命令与工具详解
Virtualmin 8.3.0 双 CLI 工具实测详解：virtualmin 275 行帮助 100+ 子命令（建域/用户/备份恢复闭环/计划模板/许可体检）与 webmin 面板运维命令（passwd/list-config/set-config/server/twofactor），含 delete-domain 无确认、create-user 正确用法等实测踩坑
Virtualmin 8.3.0 常用 CLI 命令与工具详解
目标：把 Virtualmin 8.3.0 自带的两个命令行工具——
virtualmin（275 行帮助、100+ 子命令的虚拟主机操作面）与webmin（面板自身的配置/口令/服务管理 CLI）——的常用命令族逐个讲透：参数、真实回显、适用边界。全文命令均在 Ubuntu 24.04.5 生产样本机（srv01.example.com，已建域 shop.example.com）逐条实测（2026-11-03），回显照抄。
一、环境信息
| 项目 | 值 |
|---|---|
| 操作系统 | Ubuntu 24.04.5 LTS（srv01.example.com） |
| Virtualmin | GPL 8.3.0（webmin-virtual-server 8.3.0-1-gpl） |
| Webmin | 2.670 |
| virtualmin 入口 | /usr/sbin/virtualmin（Perl 包装脚本） |
| webmin 入口 | /usr/bin/webmin（Perl 脚本） |
| 样本域 | shop.example.com（root 口令 q1w2e3r4，演示用） |
| 帮助体量 | virtualmin help 输出 275 行 |
工具定位核验（实测）：
which virtualmin webmin
/usr/sbin/virtualmin help | wc -l
/usr/sbin/virtualmin
/usr/bin/webmin
275
💡 说明：
virtualmin不是独立守护进程，而是把/usr/share/webmin/virtual-server/*.pl各模块脚本包装成统一子命令入口；webmin则管理面板自身（配置、口令、服务重启、补丁）。两者都以 root 运行、直接读写/etc/webmin/配置（文件层含义见 《Virtualmin 8.3.0 配置参数详解》）。
二、工具概览
virtualmin help 将子命令按功能分组（实测分组标题与代表命令）：
| 分组 | 代表命令 | 数量级 |
|---|---|---|
| Backup and restore | backup-domain、restore-domain、list-backup-logs、create-scheduled-backup | 8 |
| Virtual servers | create-domain、list-domains、modify-domain、get-dns、enable/disable-domain、clone/move/rename/transfer-domain、get-apache-config、list-ports | 30+ |
| Mail and FTP users | create-user、delete-user、modify-user、list-users、reset-pass、test-imap/pop3/smtp | 18 |
| Mail aliases | create-alias、create-simple-alias、list-aliases | 5 |
| Server owner limits | enable-limit、disable-limit、modify-limits | 3 |
| Extra administrators | create-admin、list-admins、modify-admin | 4 |
| Databases | create-database、modify-database-pass、set-mysql-pass、list-mysql-servers | 8 |
| Script installers | install-script、list-scripts、configure-script | 7 |
| Proxies and balancers | create-proxy、modify-proxy、list-proxies | 4 |
| PHP versions | list-php-versions、set-php-directory、modify-php-ini | 5 |
| SSL certificates | generate-letsencrypt-cert、install-cert、list-certs-expiry | 8 |
| Templates / Plans | create-template、get-template、create-plan | 10 |
| License / Repository | license-info、upgrade-license、configure-repos | 5 |
| Config history | list-config-revisions、restore-config-revision | 2 |
| Other | info、check-config、create-login-link、get-command、run-api-command、set-dkim | 20+ |
调用形态两种（实测帮助头）：
usage: /usr/sbin/virtualmin <command> [args..]
or: /usr/sbin/virtualmin help <command>
⚠️ 注意：
virtualmin -h/virtualmin --version不是合法形态，实测会报Command -h.pl was not found/Command --version.pl was not found（脚本把参数当子命令名去找同名 .pl）。查版本用virtualmin info，看帮助用virtualmin help。
三、前置条件
- 已按 《Ubuntu 24.04 安装 Virtualmin 8.3.0 指南》 完成安装，
systemctl is-active webmin返回active。 - root shell 登录样本机；所有示例可直接复制执行。
- 存在样本域 shop.example.com（安装篇第七章创建）；涉及域操作的命令若换域名即可复用。
- 脚本化消费输出时统一加
--json或--xml。
四、virtualmin 命令族详解
4.1 系统信息与体检
info——系统全貌（实测节选）：
virtualmin info
host:
hostname: srv01.example.com
os: Ubuntu Linux 24.04.5
theme version: 26.70
virtualmin edition: GPL
virtualmin version: 8.3.0
webmin version: 2.670
progs:
*
* Perl version
* 5.038002
*
* Python version
* 3.12.3
*
* BIND version
* 9.18.39
*
* Apache version
* 2.4.58
*
* PHP versions
* 8.3.6
*
* SpamAssassin version
* 4.0.0
*
* ClamAV version
* 1.5.4
💡 说明：输出为 YAML 风格键值（host/progs/mem/disk/status/fcount 等段，中间 progs 段为「每项一个
*子列表」的嵌套形态，此处节选连续两列展示）；fcount段给出各类对象计数（建域前全 0），适合做部署后断言。
check-config——配置体检（实测节选）：
virtualmin check-config
Your system has 15.56 GiB of memory, which is at or above the Virtualmin recommended minimum of 256 MiB
BIND DNS server is installed
Mail server Postfix is installed and configured
Apache supports HTTP/2 on your system
The following PHP execution modes are available : fpm fcgid cgi
MariaDB 10.11.14 is installed and running, using Unix socket authentication
list-server-statuses——受管服务状态（实测）：
virtualmin list-server-statuses
Feature Statu Description
---------- ----- ------------------------------------------------------------
web Up Apache Webserver
dns Up BIND DNS Server
mail Up Postfix Mail Server
dovecot Up Dovecot IMAP / POP3 Server
saslauthd Up Cyrus SASL Authentication Server
usermin Up Usermin Server
virus Down ClamAV Virus Scanning Server
mysql Up MariaDB Database Server
ftp Up ProFTPD FTP Server
fpm Up PHP-FPM 8.3.6 Server
💡 说明：
virus Down是常态——ClamAV 由邮件链路按需拉起，空闲即停；巡检断言应排除该项或单独白名单。
license-info——许可与容量（实测）：
virtualmin license-info
Serial number: GPL
License key: GPL
Host ID: 17794d56
Virtual servers: 1
Maximum servers: Unlimited
Servers left: Unlimited
4.2 虚拟服务器生命周期
create-domain——建域。参数骨架（实测 create-domain --help 节选）：
virtualmin create-domain --domain domain.name
--pass "password-for-new-domain" | --passfile password-file
[--parent domain.name | --alias domain.name | --superdom domain.name]
[--desc description-for-domain] [--email contact-email]
[--unix] [--dir] [--dns] [--mail] [--web] [--ssl] [--logrotate]
[--mysql] [--spam] [--virus] [--webmin] [--virtualmin-awstats]
[--default-features] | [--features-from-plan]
[--default-ip | --no-ip | --shared-ip existing.ip.address |
--allocate-ip | --ip virtual.ip.address]
[--dns-ip address | --no-dns-ip]
[--template "name"] [--plan "name"] [--limits-from-plan]
[--max-doms domains|*] [--max-mailboxes boxes] [--max-dbs databases]
[--mysql-pass password] [--acme] [--skip-warnings]
实测建域（安装篇同款命令，端到端 34 秒）：
time virtualmin create-domain --domain shop.example.com --pass q1w2e3r4 \
--desc "Shop 演示站" --email webmaster@shop.example.com \
--unix --dir --web --dns --mysql --webmin --limits-from-plan
Beginning server creation ..
...
Creating MariaDB database shop ..
.. done
Restarting PHP-FPM 8.3 server ..
.. done
All done!
real 0m34.198s
user 0m2.681s
sys 0m1.336s
list-domains——列表与机器输出（实测）：
virtualmin list-domains
Domain Username Description
------------------------------ --------------- ------------------------------
shop.example.com shop Shop 演示站
virtualmin list-domains --json | head -20
输出节选（实测首段）：
{
"data" : [
{
"name" : "shop.example.com",
"values" : {
"group_id" : [
"1002"
],
"php_fpm_socket" : [
"File /run/php/179367404951356.sock"
],
"supported_http_protocols" : [
"h2 h2c http/1.1"
],
💡 说明：
--json的values即域文件全部键的渲染视图（配置篇 5.4 的底层数据源）；还有--name-only/--id-only/--with-feature/--disabled等过滤参数（实测--long不存在，会打 usage）。
get-dns——域名解析记录（实测）：
virtualmin get-dns --domain shop.example.com
Record Type Value
------------------------------ ----- ----------------------------------------
shop.example.com. SOA srv01.example.com. root.srv01.example.co
shop.example.com. NS srv01.example.com.
shop.example.com. A 182.54.113.29
www A 182.54.113.29
webmail A 182.54.113.29
admin A 182.54.113.29
shop.example.com. SPF v=spf1 a mx a:shop.example.com ip4:10.89…
modify-domain——改属性（实测改描述）：
virtualmin modify-domain --domain shop.example.com --desc "Shop 演示站（改过描述）"
Re-loading Webmin ..
.. done
All done
disable-domain / enable-domain——临时停用。实测停用后：
virtualmin disable-domain --domain shop.example.com
.. done
All done!
curl -s -o /dev/null -w "disabled:%{http_code}\n" -H "Host: shop.example.com" http://localhost/
disabled:200
⚠️ 注意：停用后按 Host 头访问仍返回 200——请求落到了默认 vhost 的 welcome 页而非该站内容，
disable-domain关闭的是域自身 vhost/邮箱/进程池，不是「端口级拒绝」。enable-domain实测同样All done!，功能恢复。
validate-domains——配置自检。直接裸跑会提示缺参（实测）：
No features to validate specified
正确用法（实测）：
virtualmin validate-domains --domain shop.example.com --all-features
shop.example.com
All features are good
delete-domain——删除（无二次确认！）。实测试图加 --confirm 反而报参数不存在：
virtualmin delete-domain --domain shop.example.com --confirm
Unknown parameter --confirm
Deletes an existing Virtualmin virtual server and all sub-servers,
mailboxes and alias domains.
virtualmin delete-domain [--domain domain.name]*
[--user username]*
[--only]
[--preserve-remote]
去掉 --confirm 即直接执行删除（实测）：
virtualmin delete-domain --domain shop.example.com
.. deleted
virtualmin list-domains
Domain Username Description
------------------------------ --------------- ------------------------------
⚠️ 注意：
delete-domain无交互确认、无回收站，脚本里务必先backup-domain再删（4.4 节），或先--test类演练命令确认范围。
4.3 邮箱与系统用户
create-user——建邮箱用户。参数骨架（实测 create-user --help 节选）：
virtualmin create-user --domain domain.name
--user new-username
--pass "password-for-new-user" | --encpass encrypted-password |
--random-pass | --passfile password-file
[--real real-name-for-new-user]
[--ftp] [--shell /path/to/shell] [--noemail]
[--db-only <--mysql db>*] [--mysql db]*
[--extra email.address@some.domain] [--recovery address@offsite.com]
[--group name]* [--web] [--no-check-spam] [--home directory]
实测（最小三参数即建邮箱，默认特性就是「邮箱用户」）：
virtualmin create-user --domain shop.example.com --user sales --pass q1w2e3r4 --real "Sales Box"
User sales@shop.example.com created successfully
virtualmin list-users --domain shop.example.com
User Real name Mail FTP DBs Quota
-------------------- -------------------- ---- ---------- ---- ---------------
sales Sales Box Yes No No NA
ls /home/shop/Maildir/sales
cur
new
subscriptions
tmp
⚠️ 注意：给 create-user 传
--mailbox是错误用法（实测直接打 usage 退出）——邮箱地址由--user@--domain拼出，不存在独立邮箱命名参数；真实姓名用--real。
4.4 备份与恢复
backup-domain——目的地与压缩。实测 backup-domain --help 节选：
virtualmin backup-domain [--dest file]+
[--test]
[--domain name] | [--all-domains]
[--feature name] | [--all-features] [--except-feature name]
[--newformat] [--onebyone] [--strftime] [--purge days]
[--differential | --no-differential | --differential-of backup-id]
[--compression gzip|bzip2|tar|zip|zstd]
The destination can be one of :
- A local file, like /backup/yourdomain.com.tgz
- An FTP destination, like ftp://login:pass@server/backup/yourdomain.com.tgz
- An SSH destination, like ssh://login:pass@server/backup/yourdomain.com.tgz
- An S3 bucket, like s3://accesskey:secretkey@bucket
- A Google Cloud Storage bucket, like gcs://bucket
- A Dropbox folder, like dropbox://folder
💡 技术拓展：
--compression五种打包格式对比——
格式 压缩率 速度 特点 gzip 中 快 默认，通用性最好 bzip2 高 慢 体积敏感场景 zstd 高 最快 大域备份推荐 zip 中 中 Windows 侧解压友好 tar — 不压缩 只打包，交给下游工具 本文实测环境用默认 gzip（小演示域 90.85 KiB 无差异）。
实测备份（全特性到本地文件）：
mkdir -p /root/backup
virtualmin backup-domain --dest /root/backup/shop.example.com.tgz \
--domain shop.example.com --all-features
输出节选（实测首尾）：
Dumping MariaDB database shop ..
.. done
Backing up Webmin ACL files ..
.. completed in 1 seconds
Creating final backup archive ..
.. done
1 virtual servers backed up successfully
Backup completed successfully. Final size was 90.85 KiB
ls -l /root/backup
virtualmin list-backup-logs
total 108K
-rw-r--r-- 1 root root 91K Nov 3 02:50 shop.example.com.tgz
-rw-r--r-- 1 root root 12K Nov 3 02:50 shop.example.com.tgz.dom
-rw-r--r-- 1 root root 227 Nov 3 02:50 shop.example.com.tgz.info
Domains Destination Status Size
-------------------- ---------------------------------------- ------ ----------
shop.example.com Local file /root/backup/shop.example.com OK 90.85 KiB
💡 说明：一次备份产出三件套——
.tgz（数据本体）、.tgz.dom（域配置清单）、.tgz.info（备份元数据）；list-backup-logs即 GUI 备份日志的 CLI 视图。
restore-domain——恢复闭环实测。先删域（4.2 实测已删），再从备份恢复：
virtualmin restore-domain --source /root/backup/shop.example.com.tgz \
--all-domains --all-features
Re-loading Webmin ..
.. done
Re-starting Usermin ..
.. done
Restarting mail server ..
.. done
Restore completed successfully.
virtualmin list-domains
curl -s -o /dev/null -w "%{http_code}\n" -H "Host: shop.example.com" http://localhost/
ls /home/shop/public_html
Domain Username Description
------------------------------ --------------- ------------------------------
shop.example.com shop Shop 演示站
200
index.html
💡 说明：本节按「备份→删除→恢复」真实闭环展示，恢复后列表中的描述即备份时点的值；4.2 的改描述与停用/启用实验在恢复之后另行进行，不影响本回显。
list-scheduled-backups——定时任务审计（实测空表，本机未配置定时备份）：
Domains Destination Schedule
---------------------- ---------------------------------------- ---------------
4.5 计划、模板与特性元数据
virtualmin list-plans
virtualmin list-templates
virtualmin list-features
实测回显：
ID Name Quota Domains
------------------ ---------------------------------------- ---------- --------
0 Default Plan 2 GiB 0
ID Description
------------------ ------------------------------------------------------------
0 Default Settings
1 Settings For Sub-Servers
Code Description Enabled
-------------------- -------------------------------------------------- --------
unix Administration user Auto
dir Home directory Auto
dns DNS for domain Yes
mail Mail for domain Yes
web Apache website Yes
webalizer Webalizer reporting No
ssl Apache SSL website Auto
logrotate Log file rotation Auto
mysql MariaDB database Yes
postgres PostgreSQL database No
spam Spam filtering Yes
virus Virus filtering Yes
webmin Webmin login Yes
virtualmin-awstats AWStats reporting Yes
💡 说明：
list-features的 Enabled 三态——Auto表示建域时不可关（unix/dir/ssl/logrotate），Yes/No是全局默认开关，决定不带参数时特性是否默认勾选；--plan/--template与这些键的落盘位置见配置篇 5.5 节。
get-command——命令参数元数据（实测节选）：
virtualmin get-command --command create-domain | head -8
Description: Create a virtual server
domain
Binary: No
Value: domain.name
Optional: No
Repeats: No
create-login-link——免密登录链接（实测）：
virtualmin create-login-link --domain shop.example.com
https://shop.example.com:10000/session_login.cgi?session=f99a8a87963b39c543716bab38ed645f
⚠️ 注意：链接即开即登录控制台，session 一次性且有时效，用后即焚，禁止落日志。
configure-repos——仓库分支（实测 help）：
virtualmin configure-repos [--branch <stable|prerelease|unstable>]
[--serial number] [--key id] [--no-check]
4.6 其他常用命令速查（来自 275 行 help 实查）
| 场景 | 命令（参数以 virtualmin help <命令> 为准） |
|---|---|
| 查 Apache vhost | virtualmin get-apache-config |
| 查域端口 | virtualmin list-ports |
| 带宽用量 | virtualmin list-bandwidth |
| 配额修复 | virtualmin fix-domain-quota |
| 权限修复 | virtualmin fix-domain-permissions |
| 邮件链路测试 | virtualmin test-smtp / test-pop3 / test-imap |
| DKIM 批量开关 | virtualmin set-dkim |
| 批量执行 | virtualmin run-api-command |
| PHP 版本 | virtualmin list-php-versions、set-php-directory |
| 证书到期 | virtualmin list-certs-expiry |
| 重启受管服务 | virtualmin restart-server |
| 配置历史 | virtualmin list-config-revisions、restore-config-revision |
五、webmin 命令详解
/usr/bin/webmin 是面板自身运维 CLI（#!/usr/bin/env perl 开头，实测），与 virtualmin（管站点）分工不同。
5.1 通用选项（实测 --help 节选）
Usage:
webmin [options] subcommand [subcommand options]
Options:
--help, -h Print this usage summary and exit.
--config <path>, -c Specify the Webmin config directory. Defaults to "/etc/webmin".
--list-commands, -l List available subcommands.
--describe, -d When listing commands, briefly describe what they do.
--man <command>, -m Display the manual page for the given subcommand.
--version, -v Returns current Webmin version installed
webmin --version
2.670
5.2 子命令族（实测 webmin --list-commands --describe）
disable-proxy
Disable proxy-related features in Webmin.
disable-twofactor
Disable two factor authentication for a given user. Useful in cases
where the second factor (e.g. phone or USB key) has been lost.
enable-proxy
Configure the Webmin web server to be proxied through another web
server, like Apache or nginx. This is not usually recommended, and
disables some security features, but can help traverse a firewall.
language-manager
Manage Webmin/Usermin module language files ...
list-config
List one or all configuration directives for "miniserv.conf" or a module
"config" file.
passwd
This program allows you to change the password used by a Webmin user.
When a matching Unix user exists, it can change the Unix password or set a
separate password in the Webmin password file.
patch
Apply a patch to Webmin core or its modules from GitHub/GitLab, a local
file, or by downloading and replacing the entire file from a raw URL.
server
This program allows you to control Webmin web-server
set-config
Set a configuration directive in either "miniserv.conf" (the core Webmin
config) or in the specified module "config".
高频用法（语法均经 webmin --man <子命令> 实测确认，list-config 回显实测）：
# 改 root 的 Webmin/系统口令（等价 GUI「Webmin 用户」）
webmin passwd --user root
# 二因子设备丢失救砖
webmin disable-twofactor --user root
# 读配置键（实测回显）
webmin list-config --module virtual-server | grep '^defuquota'
defuquota=2097152
写配置键的官方 usage 为 webmin set-config [options] [--module] --option <option-name> --value <value>（实测 webmin set-config --help），例如：
webmin set-config --module virtual-server --option defuquota --value 5242880
💡 说明：
enable-proxy用于把 Webmin 藏到 Apache/nginx 反代后面穿越防火墙（代价是关闭部分安全特性）；与 miniserv.conf 中sessiononly=/virtual-server/remote.cgi（配置篇 5.2）配合使用。
5.3 server 子命令——面板进程控制
webmin --man server 给出的用法形态为 webmin server [command]，示例含 webmin server status（实测）：
webmin server status
输出节选（实测，隐去 cgroup 细节行）：
● webmin.service - Webmin server daemon
Loaded: loaded (/usr/lib/systemd/system/webmin.service; enabled; preset: enabled)
Active: active (running) since Tue 2026-11-03 02:36:00 UTC; 34min ago
Main PID: 4183 (perl)
Tasks: 2 (limit: 2506)
Memory: 112.3M (peak: 250.7M)
CPU: 11.152s
💡 说明：
webmin server即「control Webmin web-server」的官方 CLI 包装，底层对接 systemd；生产习惯仍推荐直接systemctl restart webmin（安装篇 4.3 实测服务为 systemd 托管）。
六、注意事项
- 破坏性命令无确认：
delete-domain、delete-user直接执行（4.2 实测--confirm不存在），脚本中先backup-domain兜底。 - 帮助入口唯一：
virtualmin不认-h/--help顶层形态（实测报Command -h.pl was not found），子命令级create-domain --help可用；总览用virtualmin help。 - 机器可读优先：所有列表命令支持
--json/--xml（4.2 实测），CI 断言别解析 ASCII 表格。 - 中文描述编码：终端非 UTF-8 时
list-domains的中文 Description 会显示为乱码（实测Shop 演示站…），数据本身无损，切 UTF-8 终端即恢复。 - 远程 API 与会话绑定：
/virtual-server/remote.cgi被 miniserv 限定sessiononly，外部脚本走 CLI 或先登录取会话，别指望裸 curl 调 API。
七、常见问题（FAQ）
Q1：virtualmin --version 报错？ 见第六章第 2 条，用 virtualmin info（4.1 实测含 virtualmin/webmin 版本）或 webmin --version。
Q2：create-user 怎么设邮箱地址？ 不能单独设——--user sales --domain shop.example.com 即 sales@shop.example.com（4.3 实测）；额外别名用 --extra。
Q3：备份恢复后 uid 变了？ 删除再恢复的域可能重新分配 uid/gid（实测恢复后 SuexecUserGroup 从 #1002 变 #1003），跨机迁移或挂载外部数据目录时用 --reuid/--reuser 控制（restore-domain help 实测列出）。
Q4：disable-domain 后站点还能访问？ 4.2 实测 disabled:200——命中的是默认 vhost 的 welcome 页，真实站点内容已下线；按域隔离访问需在防火墙/上游做 Host 级处置。
Q5：list-server-statuses 里 ClamAV 一直 Down？ 按需启动设计（4.1 说明），属预期；若邮件链路确定不需要病毒扫描，可用 virtualmin set-global-feature（参数以 virtualmin help set-global-feature 为准）全局关闭 virus 特性。
Q6：想批量改所有域的口令？ 用 virtualmin reset-pass（help 分组「Mail and FTP users」实测存在，支持按域/按用户批量），配合 --json 审计结果。
八、参考链接
- Virtualmin CLI 官方文档：https://virtualmin.com/documentation/admin/cli/
- Webmin 模块脚本源码：/usr/share/webmin/virtual-server/（本机）与 https://github.com/virtualmin/virtualmin-gpl
- 站内相关阅读：《Virtualmin 介绍与选型指南》、《Ubuntu 24.04 安装 Virtualmin 8.3.0 指南》、《Virtualmin 8.3.0 配置参数详解》、《Froxlor 2.3.16 常用 CLI 命令与工具详解》