omv-firstaid 救援工具

Web 界面打不开、改错了 IP、忘了管理员密码，这些情况下界面本身帮不了你，需要一个在控制台上也能用的工具。读完这一篇，你能运行 omv-firstaid，知道菜单里每一项做什么、什么时候用，以及哪几项会顺带改动其他设置。

开始之前

• 在 OMV 的 shell 里运行：NAS 本机接显示器和键盘，或者 SSH 登录，root 身份。
• 它是菜单式的，用方向键选择，Enter 确认，Exit 退出。菜单文字是英文，没有翻译。
• 选中一项并执行完后，菜单就退出了，要做第二件事需要重新运行一次。
• 多数菜单项通过 RPC 工作，需要 omv-engined 守护进程在运行。如果提示 Failed to connect to socket，先让它运行起来：systemctl restart openmediavault-engined。

omv-firstaid

有两项会顺带应用所有待应用的配置更改

影响范围：「Configure network interface」和「Configure workbench」在改完设置之后，都会调用 Config.applyChanges 处理所有被标记为待应用的模块，而不只是它们自己改的那一项。如果界面上还有你没点应用的更改，它们会被一起应用。

前置条件：运行这两项之前，先用 omv-salt deploy list-dirty 看看有没有待应用的模块，有的话想清楚是不是要一起应用。改网络之前确认能在本机控制台操作，因为 IP 一变，SSH 会断。

怎么回退：网络和 Web 设置改错了，可以再运行一次对应的菜单项改回来。待应用的更改被应用之后不能撤销。

菜单项一览

菜单按下面的顺序排列，具体编号以你屏幕上的为准。

菜单项	做什么	什么时候用
Configure network interface	重新配置网络接口	改坏了网络、换了网卡、IP 不对
Configure time zone	修改时区	时区不对，界面又打不开
Configure workbench	修改 Web 界面的端口、HTTPS 和证书	端口冲突、证书出错、HTTPS 把自己锁在外面
Change Workbench administrator password	重置 Web 管理员（admin）的密码	忘记了 Web 密码
Reset failed login attempt counter	重置某个用户的登录失败计数	账户因为输错密码太多次被锁
Restore configuration backup	撤销尚未应用的配置更改	改坏了配置、界面不正常
Check configuration status file	检查待应用列表文件	黄色提示条异常，或应用一直报错
Check RRD database	检查并清理性能统计数据库	性能统计图是空白的或者报错
Refresh APT package lists and clean caches	清理软件源缓存并刷新（8.3.0 起）	更新页报错、软件源列表损坏
Clear local upload package repository	清空本地上传软件包仓库	上传过的软件包让 apt 报错
Submit diagnostic report to administrator	把系统诊断报告发邮件或存到 U 盘	求助时需要提供诊断信息

Configure network interface

依次询问：选择网卡（只列出有线和无线网卡），是否配置 IPv4，用 DHCP 还是静态地址（静态时要输入地址、点分十进制的子网掩码、默认网关），是否配置 IPv6（DHCPv6、SLAAC 或静态），DNS 服务器（只能填一个，留空表示不用），是否启用网络唤醒（WOL）。无线网卡还会问网络名称（SSID）、频段、WPA2 或 WPA3、密码和是否隐藏网络。

关键行为：它会删除所有已有的网络接口配置，只留下你这次配置的这一张网卡，然后应用。有多块网卡、Bond、VLAN、网桥的机器，运行之后这些配置都没了，需要在界面里重新建。适合改坏网络之后的紧急恢复，见 改坏网络后怎么救。

Configure time zone

从列表里选一个时区。它只应用 timezone 这一个模块，不会影响别的待应用更改。

Configure workbench

依次询问 HTTP 端口（默认显示 80）；如果系统里已经有证书，再问是否启用 HTTPS、HTTPS 端口（默认 443）、使用哪个证书、是否只允许 HTTPS。保存时会同时把自动注销（Automatic logout）重置为 5 分钟。

它一次性覆盖 系统 → 工作台 → 设置（System → Workbench → Settings）里的端口、HTTPS、证书、强制使用 SSL/TLS 和自动注销，没有「只改端口」的选项。如果系统里还没有证书，或者你在「是否启用 HTTPS」时选了「否」，已有的 HTTPS 设置会被关掉。完成后会打印所有可用的访问地址。

它还有一个附带效果：保存 Web 设置会让 nginx 重新生成配置，所以界面打不开的时候，它也是重新生成 Web 服务配置的一个办法。更细的排查见 Web 界面打不开。

Change Workbench administrator password

输入两遍新密码。它改的是 admin 这个系统账户的密码，也就是 Web 界面的默认管理员。其他属于 openmediavault-admin 组的用户不受影响。完整的密码重置流程见 忘记管理员密码。

Reset failed login attempt counter

OMV 的 Web 登录用 PAM 的 faillock 限制失败次数，5 分钟内连续输错 3 次就会锁定账户，并且不会自动解锁。这一项会列出 /var/run/faillock/ 里有失败记录的用户，选一个，执行 faillock --reset --user <用户名>。没有任何用户有失败记录时，提示没有被锁定的用户。每天运行的检查脚本发现有被锁的用户时，会发邮件提醒你用这个菜单项解锁。

Restore configuration backup

OMV 保存设置时会生成修订文件 config.xml.NNNN，点击应用之后这些文件被删除，所以只有「已保存但还没应用」的更改才有修订文件。这一项取编号最大的那个，显示它与当前 config.xml 的差异，你确认之后把它恢复成当前配置，同时删除所有修订文件、清空待应用列表。没有修订文件时提示 No configuration backup found!。

它能撤销的只有未应用的更改，不是长期备份，更不是用来恢复整个系统的。原理见 配置数据库：config.xml 与 omv-confdbadm。

Check configuration status file

检查 /var/lib/openmediavault/dirtymodules.json，也就是黄色提示条背后的待应用列表，是不是合法的 JSON。文件不存在或合法时只提示一句；文件损坏时它会尝试删除。按 8.5.x 的源码，这一步的删除调用写得有问题（传给删除函数的是文件对象而不是路径），文件真的损坏时很可能直接报 TypeError，没有删掉，这一点没有在实机上验证。遇到这种情况，先确认文件确实损坏（jq . /var/lib/openmediavault/dirtymodules.json），再手动删除它。删除它相当于清空待应用列表，OMV 需要时会重新创建它（这是按源码推断的）；你原来还没应用的模块，用 omv-salt deploy run <模块> 逐个重新部署。

Check RRD database

检查 /var/lib/rrdcached/db/localhost/ 下所有的 .rrd 文件。不是合法 RRD 文件的直接删除，时间戳在未来的会询问你是否删除。如果性能统计正在运行，检查期间会临时停止 rrdcached。删除后，对应的统计图会从零开始重新积累历史。系统时间曾经跳到未来、之后又改回来，是最常见的原因。

Refresh APT package lists and clean caches

依次执行：apt clean，删除 /var/lib/apt/lists/ 下的所有内容（保留 partial 目录），删除 APT 的两个锁文件，最后 apt-get update --fix-missing。运行之前确认没有 apt 或 dpkg 在运行，可以用 pgrep -a 'apt|dpkg' 检查。对应的界面和排查见 更新失败与软件源报错。

Clear local upload package repository

删除 /var/cache/openmediavault/archives/ 里的所有 .deb 文件，重建索引，再 apt-get update。这个目录是早期「上传软件包」功能留下的本地仓库，里面的包损坏时会让 apt 报错。

Submit diagnostic report to administrator

运行 omv-sysinfo 并交出报告。邮件服务（postfix）在运行时，发邮件给 root；否则会询问是否保存到 U 盘：插入一个带文件系统的 U 盘，它会挂载分区，写入 sysinfo-<主机名>-<日期时间>.txt，再卸载。报告里有主机名、IP 和磁盘 UUID 等信息，公开之前要脱敏。

什么时候用哪一项

现象	先试
改错 IP 或网络不通	Configure network interface
浏览器连不上，访问地址提示连接被拒绝	先看 Web 界面打不开，再试 Configure workbench
提示 502 Bad Gateway 或 Failed to connect to socket	见 502 Bad Gateway 与 Failed to connect to socket
密码正确却登录失败，提示账户被锁	Reset failed login attempt counter
忘记 admin 密码	Change Workbench administrator password
刚在界面里改了一个设置，整个界面就不对了	Restore configuration backup
点应用一直报错	看 应用配置时报错，必要时 Check configuration status file
更新页面报软件源错误	Refresh APT package lists and clean caches

检查结果

操作完成后，用另一台电脑验证，而不是只相信本机的提示：

• 网络：在 shell 里 ip -br address 看 IP，在另一台电脑上能 ping 通、能打开 Web 界面。
• Web 界面：用打印出来的地址访问，确认端口和 HTTPS 符合预期。
• 密码：用新密码登录 Web 界面。
• 待应用列表：omv-salt deploy list-dirty 输出 No dirty states found.。

常见问题

菜单显示成乱码或方框。 终端不支持 dialog 的绘制方式。换一个终端，或者设置 TERM=xterm 再运行。

菜单项执行到一半报 Python 异常。 omv-firstaid 会把异常信息打印出来并退出。把最后几行记下来，通常和 omv-engined 没有运行有关，先重启它再试。

我只想知道 IP 是多少。 本机控制台登录之后，ip -br address 就能看到，不需要运行 firstaid。

参考资料

• OMV 源码：firstaid/modules.d
• 官方文档：FAQ