OMV 命令行工具一览

OMV 在 /usr/sbin/ 下带了十几个命令。读完这一篇，你能说出每个命令做什么、哪些可以放心运行、哪些会改动系统，并且知道某件事该找哪个命令。

开始之前

• 所有命令都在 OMV 的 shell（SSH 或本机控制台，root 身份）里运行，不写 sudo。
• 大部分命令支持 --help 或 -h，不确定参数时先看帮助。
• omv-salt、omv-confdbadm、omv-sysinfo 自带 Bash 补全（在 /etc/bash_completion.d/ 下），按 Tab 可以补全子命令和模块名。
• 本文按 OMV 8.5.x 的源码整理。「只读」「会改动」是读源码得出的判断，没有在实机上逐个运行验证，破坏性操作请先在测试机上试。

命令总表

命令	做什么	会改动系统吗	典型场景
omv-firstaid	控制台菜单式救援工具	取决于所选菜单项	界面打不开、忘记密码、改坏网络
omv-sysinfo	收集系统诊断信息	只读	求助时附上输出
omv-env	读写 /etc/default/openmediavault 里的环境变量	list、get 只读，set、unset 会改文件	调整界面里没有的选项
omv-salt	部署配置，相当于「应用」按钮	会	手动部署、自定义状态后重新部署
omv-confdbadm	读写配置数据库 config.xml	read、exists、list-ids 只读，其余会改	脚本读取配置、救援
omv-rpc	调用和 Web 界面相同的 RPC	取决于所调用的方法	脚本读写配置
omv-upgrade	非交互地升级全部软件包	会	命令行更新
omv-run	执行命令，可把输出发邮件	取决于所执行的命令	给脚本加邮件通知
omv-btrfs-scrub	对所有已挂载的 Btrfs 文件系统做 scrub	会产生大量读 I/O	cron 每月（或每周）自动调用
omv-sfsnapadm	列出、清理共享文件夹的 Btrfs 快照	list 只读，cleanup 会删除快照	快照管理
nginx_ensite、nginx_dissite	启用、停用 nginx 站点	会	自己加 nginx 站点

另有几个内部组件，一般不用手动运行：omv-engined（RPC 守护进程）、omv-mkaptidx、omv-mkworkbench、omv-mkrrdgraph、omv-btrfs-dfree，见本文末尾。

omv-firstaid

控制台上的菜单式救援工具，用 dialog 画界面，菜单文字是英文。它做的事都是通过 RPC 完成的，等同于在 Web 界面里操作，但界面坏了也能用。每个菜单项做什么，见 omv-firstaid 救援工具。

omv-firstaid

omv-sysinfo

依次运行 /usr/share/openmediavault/sysinfo/modules.d/ 下的诊断模块并把结果打印出来：系统版本、网络接口与路由、监听端口、防火墙规则、RAID、磁盘与挂载、/etc/fstab、软件源和已装插件等。它只收集信息，不改任何东西。

omv-sysinfo            # 运行全部模块
omv-sysinfo -l         # 列出所有模块
omv-sysinfo -c 40      # 只运行 40- 开头的一类（文件系统信息）
omv-sysinfo 40-df      # 只运行某个模块，名称只写一部分也可以，前提是只匹配到一个模块

模块编号的含义写在模块目录的 README 里：00 版本，10 系统设置，20 网络，30 系统服务，40 文件系统，50 软件包，60 硬件，90 各类服务。

贴到论坛之前先脱敏

输出里有主机名、IP 地址、路由、监听端口和磁盘 UUID。公开发布前先替换掉这些信息。

omv-env

读写 /etc/default/openmediavault 中以 OMV_ 开头的环境变量。完整用法和常用变量见 环境变量：调整界面里没有的选项。

omv-env list                      # 所有可用的变量名
omv-env get                       # 当前文件里已设置的变量
omv-env get <变量名>              # 只看某个变量，可写多个
omv-env get --value-only <变量名> # 只输出值
omv-env set -- <变量名> <值>      # 设置
omv-env unset <变量名>            # 删除，恢复内置默认值

list、get 都支持 --json。变量名必须以 OMV_ 开头；set 和 unset 会重写整个文件，只保留 OMV_ 开头的行并按名称排序，所以你手写在文件里的注释会丢失。

omv-salt

把数据库里的配置变成系统里真正的配置文件，就是点击黄色提示条上的应用之后后台执行的那条命令。用法和自定义状态见 Salt 部署与自定义配置。

omv-salt deploy list                 # 所有可部署的模块
omv-salt deploy list-dirty           # 已保存、尚未应用的模块
omv-salt deploy run <模块>...        # 部署一个或多个模块
omv-salt deploy run --append-dirty   # 部署所有待应用的模块，成功后清空待应用列表
omv-salt stage list                  # setup、prepare、deploy、all
omv-salt stage run <阶段>            # 运行一个阶段

deploy run 还有 --no-color 和 -q（--quiet）。模块名不存在时以退出码 100 结束。

omv-confdbadm

读写配置数据库。直接运行 omv-confdbadm 会列出全部子命令：

子命令	作用	是否只读
list-ids	列出所有数据模型 ID，例如 conf.service.ssh	只读
read	读取一个或多个配置对象，输出 JSON	只读
exists	检查对象是否存在，用退出码表示结果	只读
update	写入（替换）一个配置对象	会改
delete	按 UUID 或过滤条件删除配置对象	会改
create	运行某个数据模型的「创建默认配置」脚本	会改，装机时用
populate	从系统读取信息填充数据库	会改，在 Debian 上装 OMV 后用
migrate	运行配置迁移脚本	会改，升级时由安装包调用

update、delete、create、migrate 在动手前会把 config.xml 复制到临时文件，出错时自动回滚。读写方法、过滤条件和安全流程见 配置数据库：config.xml 与 omv-confdbadm。

omv-rpc

调用 omv-engined 守护进程里的 RPC，和 Web 界面走的是同一套接口。语法是 omv-rpc [选项] <服务> <方法> [参数]，参数是一段 JSON；-u 指定以哪个用户的身份调用，默认是 admin。成功时把结果以 JSON 打印到标准输出，失败时把错误 JSON 打印到标准错误，退出码为 1。

omv-rpc -u admin 'FileSystemMgmt' 'enumerateMountedFilesystems' '{"includeroot": true}'

只有 root 和 openmediavault-engined 组的成员能连到 RPC 的 socket。服务和方法清单、调用示例见 omv-rpc 与 JSON-RPC 接口 和 用 omv-rpc 写自动化脚本。

omv-upgrade

非交互地更新软件包索引并升级全部已装软件包，等同于 系统 → 更新管理 → 更新（System → Update Management → Updates）里的升级系统（Upgrade system）。它的内部流程是：先 apt-get update，再模拟一次升级，如果模拟结果会移除 openmediavault 软件包本身就中止，否则执行 apt-get dist-upgrade。

omv-upgrade

默认的 apt 参数写在环境变量 OMV_UPGRADE_APT_ARGS 里，包含 --auto-remove、--fix-broken 和 --force-confold（遇到配置文件冲突时保留本地版本）。升级会自动处理依赖，所以升级前要有系统盘备份，升级后看是否需要重启。更新的完整流程见 系统更新。

计划任务与维护用的辅助命令

omv-run：执行一条命令，加 -e 时把输出通过邮件发给指定用户。写自己的脚本想要邮件通知时可以用。

omv-run [-e] [-s <主题>] [-a <邮件头>] [-u <收件用户>] <命令>

omv-btrfs-scrub：对所有已挂载的 Btrfs 文件系统（按 UUID 去重）依次做 scrub，-e 把每个设备的报告发邮件给 root。scrub 的优先级和是否只读由环境变量 OMV_BTRFS_SCRUB_PRIORITY（默认 -c 2 -n 4）和 OMV_BTRFS_SCRUB_READONLY（默认 no）控制。系统自带的 cron 任务会每月（默认）调用它，周期由 OMV_BTRFS_SCRUB_PERIOD 决定。Btrfs 维护见 Btrfs 维护：scrub、balance 与换盘。

omv-sfsnapadm：管理共享文件夹的 Btrfs 快照。

omv-sfsnapadm list             # 列出所有共享文件夹的快照
omv-sfsnapadm cleanup -s       # 模拟清理，不删除任何快照
omv-sfsnapadm cleanup          # 按快照保留策略清理

cleanup 读取数据库里的快照生命周期设置，没有启用时直接以退出码 1 退出。系统每小时会自动调用一次。

nginx_ensite / nginx_dissite：在 /etc/nginx/sites-enabled/ 里创建或删除指向 /etc/nginx/sites-available/ 的符号链接。你要自己加网站时，把配置文件放在 sites-available，再用它启用，不要去改 OMV 自己的 nginx 配置。

nginx_ensite <站点文件名>
nginx_dissite <站点文件名>

内部组件

下面这些命令由系统或安装包自动调用，日常不需要手动运行：

命令	作用
omv-engined	RPC 守护进程，通过 socket 接收 RPC。由 systemd 管理，选项 -d、-f、-x 用于调试
omv-mkaptidx	每次 apt-get update 后由 APT 触发，重建「可用插件」和「可升级软件包」的索引文件
omv-mkworkbench	安装或卸载插件后由 dpkg 触发，重新生成界面的菜单、路由、仪表盘和翻译配置
omv-mkrrdgraph	用 RRD 数据生成性能统计图
omv-btrfs-dfree	Samba 的 dfree command，在 Btrfs 上计算共享报告的剩余空间

插件装完界面不对时，问题多半出在 omv-mkworkbench 生成的文件和浏览器缓存之间，见 插件装完界面不对。

其他地方的命令

• omv-release-upgrade：大版本升级命令。只在一个大版本的最后几个小版本里提供，例如 OMV 7.7.24-6 起加入，用来升级到 OMV 8；OMV 8 的核心包里没有它。升级流程见 大版本升级：从 OMV 7 到 OMV 8。
• omv-aptclean、omv-changebackports：来自 omv-extras，见 安装 omv-extras。
• /usr/share/openmediavault/scripts/helper-functions：一组 shell 辅助函数，source 之后可以用 omv_config_get、omv_get_sharedfolder_path、omv_module_set_dirty、omv_exec_rpc 等。官方插件的安装脚本大量使用它，写自己的脚本时可以按 Tab 补全 omv_ 开头的函数名查看。

检查结果

下面几条命令都是只读的，能正常输出说明命令行环境没问题：

omv-env list | head                 # 能列出变量名
omv-confdbadm list-ids | head       # 能列出数据模型 ID
omv-salt deploy list | head         # 能列出可部署的模块
omv-salt deploy list-dirty          # 没有待应用的更改时输出 No dirty states found.
omv-rpc System getInformation       # 能返回系统信息的 JSON

常见问题

omv-rpc 报 Failed to connect to socket。 omv-engined 没有运行。先在 OMV 的 shell 里检查 systemctl status openmediavault-engined，再用 omv-firstaid 处理，见 502 Bad Gateway 与 Failed to connect to socket。

omv-confdbadm 说 No valid data model ID。 数据模型 ID 必须是 omv-confdbadm list-ids 列出的名字，例如 conf.system.sharedfolder。装了插件之后列表会变长。

omv-salt deploy run 之后黄色提示条还在。 不带 --append-dirty 的 deploy run 只部署你指定的模块，不会清空待应用列表。要清空，用 --append-dirty，或者在界面里点应用。

参考资料

• OMV 源码中的命令：deb/openmediavault/usr/sbin
• 官方文档：Internal Tools、Custom Configuration