OpenMediaVault 使用指南

外观

入门OMV 8.x

资料核查：2026-10-23T00:00:00.000Z；尚无本站实机验证记录，请按文中的检查步骤确认本机结果。

OMV 是怎么工作的：配置数据库与「应用」按钮 ​

界面上的每个设置，OMV 都是先写进一个数据库，等你点了黄色提示条上的应用，才按数据库的内容重写系统的配置文件、重启相关服务。理解了这件事，「点了保存怎么没生效」和「我手改的配置怎么被改回去了」大部分都有答案。

先说结论 ​

  1. 保存 = 写进配置数据库，并把相关模块标记为「待应用」。这时系统还没变。
  2. 应用 = 按数据库的内容完整重写配置文件，并重启或重载服务。应用成功之后，这一批改动就不能再撤销了。
  3. 手改被 OMV 接管的配置文件，会在下一次相关模块被应用时被覆盖，而且手改的内容永远不会出现在界面上。

一张图看懂 ​

text
浏览器 ──HTTP──> nginx ──FastCGI──> PHP（php-fpm）──套接字──> omv-engined
                                                               │
                  保存：写 /etc/openmediavault/config.xml ◄──────┤
                  同时把模块名记进 /var/lib/openmediavault/dirtymodules.json
                                                               │ 点「应用」
                                                               ▼
                       omv-salt deploy run <模块名> ──> 重写配置文件 ──> 重启服务

各个部分是什么 ​

组成是什么
Web 界面用 TypeScript、Angular 和 Angular Material 写的前端，由 nginx 提供
后端PHP 代码，处理界面发来的 RPC 请求
omv-enginedRPC 守护进程，后端的 PHP 代码都在它里面执行。nginx 经过 PHP 的 FastCGI 套接字和它通信
config.xml配置数据库，一个 XML 文件，位置是 /etc/openmediavault/config.xml
监听器后端模块里监听数据库变化的代码，数据一变就把自己负责的模块标记为待应用
dirtymodules.json列出所有待应用模块的文件，位置是 /var/lib/openmediavault/dirtymodules.json
Salt 与 omv-salt部署工具，每个服务对应一个 Salt 状态，状态文件在 /srv/salt/omv/ 下，负责把数据库内容渲染成配置文件

数据库里的内容长这样，下面是新装系统里 Web 界面的默认设置，仅作示意，不要手改：

xml
<webadmin>
  <port>80</port>
  <enablessl>0</enablessl>
  <sslport>443</sslport>
  <forcesslonly>0</forcesslonly>
  <timeout>5</timeout>
</webadmin>

点保存时发生了什么 ​

  1. 前端把这个页面表单里的所有字段（包括你没改的）通过 RPC 提交。
  2. 后端写入 config.xml 之前，先把当前的数据库复制成一份修订文件，依次命名为 config.xml.0001、config.xml.0002……每保存一次，多一份。这些修订文件是「撤销」的依据。
  3. 后端把新内容写进 config.xml。
  4. 后端模块的监听器发现自己负责的数据变了，就把模块名写进 dirtymodules.json。官方文档的例子：改了 SMB 的设置，会得到 samba 和 zeroconf 两个条目，因为 Avahi 要根据 Samba 是否启用来公布服务。
  5. 界面发现有待应用的模块，就在页面顶部显示黄色提示条。

模块之间还有关联。比如改共享文件夹或它的权限，只要这个共享被 SMB 引用，samba 模块也会被标记。所以你可能只改了一个权限，提示条里却出现了 SMB 相关的模块，这是正常的。

点应用时发生了什么 ​

  1. 点提示条上的对勾图标，确认后，界面被遮罩，显示「请稍等，正在应用变更后的配置……」。
  2. 后端读出待应用的模块，按它们之间的先后依赖排序，依次部署。多数服务模块的部署动作就是执行 omv-salt deploy run <模块名>：Salt 按数据库的内容完整重写对应的配置文件，再重启或重载服务。官方文档的例子：samba 会重写 /etc/samba/smb.conf 并重启 Samba，zeroconf 会重写 /etc/avahi/services/ 下的几个服务文件并重启 Avahi。
  3. 部署成功后，待应用列表清空，全部修订文件也被删除，界面弹出通知「应用已变更的配置」，附上这次更新了哪些模块。所以应用之后，这一批改动就不能再撤销了。

日常请用界面上的应用。在 shell 里手动部署属于进阶操作，见Salt 部署与自定义配置。

撤销是怎么回事 ​

点提示条上的撤销图标并确认，OMV 用编号最小的那份修订文件覆盖 config.xml，也就是退回到这一批未应用更改之前的状态；然后删除全部修订文件，清空待应用列表，刷新页面。

撤销只回滚还没应用的数据库改动，而且是这一批改动全部回滚，不能只撤销其中某一项。应用成功之后，修订文件已经被删掉，就没有可撤销的东西了。修订文件的细节，以及 omv-firstaid 怎么用它们，见配置数据库：config.xml 与 omv-confdbadm。

不是所有操作都要应用 ​

有些操作会立刻执行，带一个进度对话框，不经过黄色提示条，例如擦除磁盘、创建文件系统、安装和卸载插件。它们执行完就是真的改了系统，撤销救不了它们。官方文档也说，并不是每个组件都走「保存、标记、应用」这条路，文件系统的后端机制就复杂得多。

为什么手改配置文件会被覆盖 ​

OMV 不解析配置文件，它只认数据库。后果有两个：

  • 你手改的内容不会出现在界面上，界面显示的永远是数据库里的值。
  • 下一次相关模块被应用时，Salt 会把整个文件重写，你的改动就没了。哪怕这次应用是由另一个设置触发的，也一样。

官方文档列出了不要手改的文件，常见的有：

文件或目录由谁生成想改怎么办
/etc/fstab 中 openmediavault 标记之间的部分文件系统与挂载用界面；挂载选项用环境变量，见文件系统挂载选项与 fstab
/etc/samba/smb.confSMB 服务用 SMB 页面的扩展选项
/etc/exportsNFS 服务用 NFS 共享的扩展选项；NFSv4 的伪根选项用环境变量
/etc/proftpd/proftpd.confFTP 插件用 FTP 页面的扩展选项
/etc/netplan/ 下带 openmediavault 的文件网络接口用界面；界面没有的配置见自定义网络配置
nginx 的 openmediavault-webgui 站点和 /etc/nginx/openmediavault-webgui.d/Web 界面自己的网站放进 /etc/nginx/sites-available，用 nginx_ensite <站点名> 启用，别碰 OMV 的文件
monit、postfix 的配置服务监控、邮件通知用界面里的通知设置

这只是常见的几个，完整索引见配置文件与目录索引。

想改界面里没有的选项，按这个顺序 ​

  1. 扩展选项：SMB、NFS、FTP 等服务的页面带有这个字段，可以追加界面没有的指令，保存、应用后写进配置。
  2. 环境变量：用 omv-env 命令，或者装官方的 envvars 插件，在 系统 → 环境变量（System → Environment Variables）里改。适合调整那些写死在 Salt 模板里的默认值。
  3. 自定义 Salt 状态：在对应服务的 Salt 目录下放一个 <N>xxxx.sls 文件，N 在 0 到 100 之间，按数字顺序执行。扩展选项和环境变量能解决的，不要走这一步。

对应的详细写法见环境变量、Salt 部署与自定义配置和配置数据库。

不要往 OMV 里随便装软件

OMV 和它所基于的 Debian 版本绑得很紧。官方文档的几条红线：不要装 apache，它会导致 openmediavault 包被卸载，界面直接不可用；不要自己从 Debian 的 backports、testing 或 experimental 装软件包（OMV 自己为内核启用的 backports 源除外，那是它管理的）；不要用 pip 覆盖 apt 已经装好的 Python 包。额外软件优先用容器。

界面坏了的三种典型情况 ​

OMV 的界面依赖三个外部组件，对应三种典型报错，官方文档的结论是都可以先用 omv-firstaid 处理：

你看到的原因先做什么
浏览器提示连接被拒绝（Connection refused），什么都不显示nginx 没跑起来。对 sites-available 目录里的语法错误很敏感，一个不合格的站点文件就能让它起不来本机登录控制台运行 omv-firstaid；把不合格的站点文件移出 sites-available
界面提示 Failed to connect to socket: No such file or directoryomv-engined 没有运行同上
502 Bad Gatewayphp-fpm 的套接字没有运行，不常见，多见于动过 PHP 套接字或 systemd 配置之后同上

排查步骤见Web 界面打不开和502 Bad Gateway 与 Failed to connect to socket，救援工具见omv-firstaid 救援工具。

检查结果 ​

下面用一个无害的设置，亲眼看一遍「保存、待应用、撤销」。全程不会改动系统：最后用撤销收尾。

  1. 在 OMV 的 shell 里确认当前没有待应用的更改：

    sh
    # 在 OMV 的 shell 里执行
omv-salt deploy list-dirty

    没有待应用的模块时，输出是 No dirty states found.。

  2. 打开 系统 → 工作台 → 设置（System → Workbench → Settings），记下 自动注销（Automatic logout）当前的值（默认是 5 分钟），改成另一档，点保存。

  3. 页面顶部出现黄色提示条。点它上面的显示详情图标，可以看到「将更新以下模块」。

  4. 回到 shell，再运行一次 omv-salt deploy list-dirty，会列出待应用的模块。按源码，Web 界面的设置会标记 nginx 和 monit，以你机器上的输出为准。再看一眼数据库的修订文件：

    sh
    # 在 OMV 的 shell 里执行
ls -l /etc/openmediavault/config.xml*

    有待应用的更改时，除了 config.xml，还会多出带数字后缀的修订文件，例如 config.xml.0001，每保存一次多一份；应用或撤销之后，它们全部被删掉。具体输出以你机器上的为准。

  5. 点提示条上的撤销图标并确认。页面刷新，提示条消失，自动注销回到原来的值，omv-salt deploy list-dirty 再次输出 No dirty states found.。

如果你想看完整的一轮，把第 5 步换成应用：Web 界面的设置会让 nginx 重新部署，界面可能短暂无响应。改完记得把值改回来。

常见问题 ​

点了保存，提示条没有出现。 有些页面的操作是立刻执行的（见上文），不经过提示条。也可能页面没刷新，先刷新一下，再用 omv-salt deploy list-dirty 看看有没有待应用的模块。

提示条里出现了我没改过的模块。 模块之间有依赖，改共享文件夹会牵动 SMB，插件也可能把模块标记为待应用。这是设计如此，不是出错。

点应用后报错。 先看报错里提到的模块名，再看应用配置时报错。

我能用命令行改配置吗？ 能，用 omv-rpc 或 omv-confdbadm，但改完必须自己把相关模块标记为待应用并部署，否则只是改了数据库，系统没变。见配置数据库。

OMV 有配置备份吗？ 官方没有正式的备份与还原功能。重装时，旧的 config.xml 只能当参考。上面的修订文件不是备份：它们只在「保存之后、应用之前」存在，应用成功后就被删除。见OMV 配置怎么留底。

参考资料 ​

OpenMediaVault 非官方中文使用指南，与 openmediavault 项目及其开发者无隶属关系。