502 Bad Gateway 与 Failed to connect to socket

适用范围

• 浏览器显示 502 Bad Gateway。
• 界面上弹出错误 Failed to connect to socket: No such file or directory。

这两种提示都说明 nginx 在运行，但后端没有就绪。常见的时机：系统更新或大版本升级之后、系统盘写满之后、内存耗尽之后、动过 PHP 或 nginx 配置之后、安装或卸载插件之后。

不适用：浏览器连接被拒绝或超时，见Web 界面打不开。

开始排查前

OMV 的 Web 界面是三个组件接力工作，每一层靠一个 Unix socket 对接：

浏览器 → nginx → php-fpm → omv-engined → 配置数据库与系统
         (FastCGI socket)   (engined.sock)

你看到的现象	说明	重点检查
502 Bad Gateway	nginx 连不上 php-fpm 的 socket	php8.4-fpm
Failed to connect to socket: No such file or directory	PHP 连不上 omv-engined 的 socket	openmediavault-engined
连接被拒绝	nginx 本身没运行	见Web 界面打不开

OMV 用 monit 监控这三个组件，进程死掉后每隔约 30 秒会尝试重新拉起。所以等一两分钟问题就消失，说明是临时故障；反复出现，就说明有持续的原因（磁盘满、内存不足、配置错误）。

修复动作的影响范围

影响范围：重启这三个组件只影响 Web 界面，持续几秒到几十秒，文件共享和容器不受影响。dpkg --configure -a 和 apt-get -f install 会重新配置软件包，期间可能重启 Samba 等服务，共享会短暂中断。

前置条件：先确认系统盘没有写满、内存没有耗尽。修复软件包时不要在可能断电的情况下进行，也不要同时有别的 apt 进程在跑。

回退办法：下面的状态检查都是只读的。重启服务无需回退；如果是你手工改过 PHP、nginx 配置导致的故障，用 omv-salt deploy run 让 OMV 按数据库重写它接管的那一份。

排查步骤

1. 看三个组件的状态

# 在 OMV 的 shell 里执行（只读）
systemctl status nginx php8.4-fpm openmediavault-engined --no-pager
ls -l /var/lib/openmediavault/engined.sock /run/php/php8.4-fpm-openmediavault-webgui.sock
monit summary

• 三个都是 active (running)，两个 socket 文件都存在：后端本身没问题，换个浏览器或刷新试试，仍有问题往下看日志。
• 哪个不是 active，就看后面对应的小节。

2. 引擎没运行（Failed to connect to socket）

引擎的 socket 是 /var/lib/openmediavault/engined.sock。它不存在，说明 omv-engined 没起来。

# 在 OMV 的 shell 里执行
systemctl start openmediavault-engined
journalctl -u openmediavault-engined -b --no-pager | tail -n 40

启动失败时，按日志里的线索排查，常见原因有：

• 系统盘写满，或根文件系统变成只读：见系统盘满了、文件系统变成只读。
• 内存耗尽，进程被系统杀掉：journalctl -k -b --no-pager | grep -iE 'out of memory|oom'。官方建议新手至少 4 GiB 内存。
• 软件包更新到一半被中断：dpkg --audit 有输出就属于这种情况，见第 5 节。
• 配置数据库损坏：用 xmlstarlet val /etc/openmediavault/config.xml 检查 XML 是否合法。合法性出问题时，先看 /etc/openmediavault/ 里有没有 config.xml.0001 这样的修订文件：它们只在「已保存、未应用」期间存在，其中编号最大的一份是最近一次改动之前的完整副本，可以用来对比或还原，动手前先读配置数据库：config.xml 与 omv-confdbadm。没有修订文件，就只能从你自己留的备份恢复，见OMV 配置怎么留底。

引擎没起来时，omv-firstaid 也有一部分用不了

omv-firstaid 里的网络、时区、工作台、重置 Web 管理员密码、恢复配置备份这几项，都是通过 omv-engined 的 RPC 完成的，引擎没运行时会报同样的 socket 连接错误。而清理 APT、重置登录失败计数、检查配置状态文件这几项不依赖引擎。所以顺序是：先用 systemctl 把引擎拉起来，再用 omv-firstaid 做其他事。

3. php-fpm 没运行（502）

# 在 OMV 的 shell 里执行
php-fpm8.4 --test
systemctl restart php8.4-fpm
journalctl -u php8.4-fpm -b --no-pager | tail -n 40

• php-fpm8.4 --test 报配置错误：如果你改过 PHP 的配置，把改动还原。OMV 接管的那一份（/etc/php/8.4/fpm/pool.d/openmediavault-webgui.conf）可以让它重写：

# 在 OMV 的 shell 里执行；会先执行配置测试，通过后才重启
omv-salt deploy run phpfpm

• systemctl status 提示找不到 php8.4-fpm.service：说明 PHP 8.4 没装好。OMV 8 基于 Debian 13，使用 PHP 8.4。大版本升级半途失败时会出现这种情况，见第 5 节和大版本升级：从 OMV 7 到 OMV 8。

4. nginx 有问题

systemctl status nginx 不是 active 时，按Web 界面打不开的第 4 步检查端口占用和配置语法。

5. 软件包状态不一致

# 在 OMV 的 shell 里执行（只读）
dpkg --audit

没有输出表示正常。有输出说明有软件包停在未配置完成的状态，这时才执行修复：

# 在 OMV 的 shell 里执行；确认没有其他 apt 进程在运行
dpkg --configure -a
apt-get -f install

之后再运行一次更新。更新相关的报错和处理，见更新失败与软件源报错。

6. 引擎起不来，又看不出原因（进阶）

让引擎在前台运行，直接看它输出的错误：

# 在 OMV 的 shell 里执行
# 先让 monit 不再自动拉起它
monit unmonitor omv-engined
systemctl stop openmediavault-engined
# -d 调试模式，-f 前台运行；复现问题后按 Ctrl+C 退出
omv-engined -d -f
# 看完之后恢复
systemctl start openmediavault-engined
monit monitor omv-engined

确认恢复

1. systemctl is-active nginx php8.4-fpm openmediavault-engined 三项都是 active，monit summary 里这三个进程都是 Running。
2. 刷新登录页并登录，各页面（例如 存储器 → 文件系统（Storage → File Systems））能正常加载数据，不再出现 socket 错误。
3. 重启 NAS 一次，确认重启后仍然正常。

仍未解决

附上：第 1 步的三个组件状态、每个异常组件的最近 40 行日志、df -h / 和 free -h 的输出，以及问题出现前做过的操作（更新、装卸插件、改配置）。分享前去掉主机名和 IP，读如何有效求助。

参考资料

• OMV 官方文档：How does it work? 说明了界面的三类故障：nginx 配置错误、omv-engined 没运行、php-fpm socket 没运行
• 本站：OMV 是怎么工作的：配置数据库与「应用」按钮、omv-firstaid 救援工具