应用配置时报错

适用范围

点击页面顶部黄色的待应用的配置更改提示条上的应用（Apply）之后，弹出错误窗口、任务失败，黄色提示条仍然在。报错的内容里常常带有 omv-salt、Result: False 或某个服务的名字。

不适用：整个界面都连不上后端（出现 Failed to connect to socket），见502 Bad Gateway 与 Failed to connect to socket。

开始排查前

先理解 OMV 是怎么「应用」的：在界面里点保存，只是把新设置写进配置数据库 config.xml，并把相关模块标记为「待应用」，所以才出现黄色提示条。点应用之后，OMV 对每个待应用的模块依次运行 omv-salt deploy run <模块>，重写它接管的配置文件，再重启服务。原理见OMV 是怎么工作的：配置数据库与「应用」按钮。

应用失败时的状态：

• 新设置已经保存在数据库里，没有丢。
• 失败的那次应用不会把模块从待应用列表里移除，所以提示条还在。原因解决之后，再点一次应用就行。
• 失败之前已经成功部署的模块，下次应用时会再部署一次，这是无害的。
• 「已保存、未应用」期间，数据库每次被改动之前都会备份成 config.xml.0001、config.xml.0002 这样的修订文件。撤销和 omv-firstaid 的恢复功能都靠它们。应用成功之后这些修订文件会被全部删除，所以它们只存在于这段时间里，不是长期备份，详见配置数据库：config.xml 与 omv-confdbadm。

重新应用、撤销、恢复的影响范围

影响范围：重新应用会再次重写这些模块的配置文件并重启对应的服务，SMB、网络、Web 界面等会短暂中断。撤销（Undo）会丢弃全部尚未应用的设置更改。

前置条件：先读清报错，并记下你刚才改了什么。展开黄色提示条能看到待应用的模块列表。

回退办法：撤销之后，被丢弃的更改无法找回，只能重新设置，所以先截图或记录。omv-firstaid 的恢复配置备份，会用编号最大的修订文件覆盖当前配置，覆盖之前会先显示差异并要求确认。无论是撤销还是 firstaid 恢复，完成后全部修订文件都会被删除，只能回退这一次，不能再退回到恢复之前的状态。

排查步骤

1. 看清楚哪些模块待应用

点黄色提示条上的显示详情图标，或者点击提示文字，展开之后，「将更新以下模块」下面列出了模块名，例如 samba、avahi、nginx、fstab。

也可以在 shell 里只读地查看：

# 在 OMV 的 shell 里执行（只读）
omv-salt deploy list-dirty

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

2. 读出失败的原因

失败时，界面的任务窗口里是 Salt 的状态报告，每个步骤都有 ID、Function、Name、Result、Comment 几项。找 Result: False 的那一段，它的 Comment 就是原因。

要看完整输出，在 shell 里对出问题的模块单独运行：

# 在 OMV 的 shell 里执行；<模块> 是第 1 步里看到的模块名，例如 samba
# 注意：这会真正部署该模块，效果和点「应用」一样，会重写配置文件并重启服务
omv-salt deploy run --no-color <模块>

模块名大多与 omv-salt deploy list 列出的状态名一致；名字对不上时，用 omv-salt deploy list 看有哪些状态可用。手动运行不会清除黄色提示条，修好之后仍然要在界面点一次应用。

3. 常见原因对照

失败的模块	常见原因	怎么处理
samba	部署前会用 samba-tool testparm 检查配置。SMB 设置或某个共享里的扩展选项（Extra options）写了无效的参数，检查就会失败	删掉或修正扩展选项，再应用
nginx	部署前会运行 nginx -t。常见原因是端口被容器占用、所选证书文件缺失、sites-available 里有错误的站点文件	见Web 界面打不开的第 4 节
phpfpm	部署前会运行 php-fpm8.4 --test，PHP 配置被改坏了	见502 Bad Gateway的第 3 节
fstab	挂载失败：设备不存在或文件系统损坏	见磁盘或文件系统不见了
systemd-networkd	网络接口配置不合法，或网卡名变了	见改坏网络后怎么救
monit、postfix、chrony、rsyncd 等	对应服务的配置或依赖有问题	读 Comment，再看该服务的日志：journalctl -u <服务名> -b --no-pager
任何模块	系统盘写满，或根文件系统变成只读	见系统盘满了

4. 修好原因之后重新应用

回到界面，点应用，确认窗口选确定。成功后会提示「应用已变更的配置」，并列出已更新的模块，提示条消失。

5. 原因不明，或改动太多：撤销或恢复

• 撤销：点提示条上的撤销图标，确认「确定要撤销配置变更？」。OMV 会用编号最小的修订文件（也就是你第一次改动之前的状态）覆盖配置数据库，清空待应用列表，界面随后重新加载。你尚未应用的全部更改都会丢失。
• 只回退最近一次改动：在 NAS 本机运行 omv-firstaid，选 Restore configuration backup。它取编号最大的修订文件（即最近一次改动之前的状态），先让你选择是否查看差异，再询问是否恢复（默认答案是「否」）。它通过 omv-engined 完成，引擎没运行时用不了。
• 想在撤销之前把当前的 config.xml 留一份，复制到 /root 下，不要放进 /etc/openmediavault/：应用成功后，OMV 会把那个目录里所有以 config.xml. 开头的文件都当成修订文件删掉。长期的配置留档见OMV 配置怎么留底。

6. 待应用状态文件异常

少数情况下，记录待应用模块的 /var/lib/openmediavault/dirtymodules.json 本身损坏（不是合法的 JSON），应用会一直失败。omv-firstaid 里的 Check configuration status file 会检查这个文件，不合法时尝试删除它。这个文件只记录模块名字，删除后待应用列表会清空，相关模块要靠你重新保存设置，或手动运行 omv-salt deploy run <模块> 来部署。这种情况很少见，动手前先确认前面几步都排除了。

按当前的源码，这个菜单项删除文件的写法可能有问题，有可能只报错、没有真正删掉文件，以你实机上的表现为准。确认文件内容确实不是合法的 JSON（正常的内容形如 ["samba","avahi"]），并且 firstaid 没有删掉它的时候，可以把它移到别处，效果和删除一样，还留有备份：

# 在 OMV 的 shell 里执行；先看内容，确认确实损坏再移走
cat /var/lib/openmediavault/dirtymodules.json
mv /var/lib/openmediavault/dirtymodules.json /root/dirtymodules.json.bad

确认恢复

1. 黄色提示条消失，出现「应用已变更的配置」的提示，并列出了已更新的模块。
2. omv-salt deploy list-dirty 输出 No dirty states found.。
3. 相关服务恢复正常：例如改的是 SMB，就从客户端连一次共享；改的是网络，确认能重新访问界面。同时 systemctl --failed 没有失败的单元。
4. 重启一次，确认配置在重启后依然有效。

仍未解决

附上：展开提示条之后的模块列表、任务窗口里 Result: False 那一段完整的文字、对应模块的 omv-salt deploy run --no-color <模块> 的完整输出、对应服务的 journalctl 日志，以及你应用之前改了哪些设置。读如何有效求助。

参考资料

• OMV 官方文档：How does it work?
• 本站：Salt 部署与自定义配置、OMV 命令行工具一览、查看系统日志