容器启动失败

适用范围

用 Compose 插件管理的容器，出现下面这些情况：

• 点上线（Up）之后报错，任务窗口里有红色信息。
• 状态一直是 Exited 或 Restarting，应用打不开。
• 文件列表里状态是「下线」或「混合」。

不适用：报端口已被占用，见端口冲突；NAS 重启之后容器没有自动起来，见重启后容器没起来。

omv-extras 的文档指出，Docker 应用跑不起来，绝大多数情况与 OMV 或 Compose 插件无关，原因是镜像架构选错、网络模式不对、配置问题（例如 OMV 与容器抢 80 端口）、权限问题，或者应用本身。所以排查的重点是容器自己的日志。

开始排查前

重建容器之前，先确认数据在哪里

影响范围：重建（先下线再上线）会删除旧容器、创建新容器。挂载到共享文件夹的数据和命名卷里的数据不受影响，但没有挂载卷、写在容器自己可写层里的数据会丢失。

前置条件：先看 compose 文件的 volumes:，分清哪些是主机上的路径（安全）、哪些是命名卷（留在 Docker 的存储里）、哪些根本没有挂载。数据库类应用先备份，见更新与备份容器。

回退办法：不要用 down -v，不要点 Compose 工具菜单里的 Down all，也不要使用 Prune 菜单里清理卷或整个系统的项目，它们会删除卷或所有容器，无法撤销。

排查步骤

1. 看状态（只读）

在 服务 → Compose → 文件（Services → Compose → Files）里，状态列是「上线」「已停止」「下线」或「混合」。想看到容器级别的信息，在同一个菜单下的「服务」页面查看。在 shell 里：

# 在 OMV 的 shell 里执行（只读）
docker ps -a

看 STATUS 一列：

• Exited (1)：应用自己退出了，看日志。
• Exited (137)：进程被强制杀死，常见于内存不足。
• Restarting (1)：应用在反复崩溃、重启。
• Created：容器创建了，但没有启动成功。

2. 看日志

在界面里选中该栈，用日志功能查看。在 shell 里：

# 在 OMV 的 shell 里执行（只读）；<栈名> 是 compose 文件的名称
omv-compose-run <栈名> logs --tail 100

omv-compose-run 会带上和界面相同的 compose 文件与环境变量参数，在 Compose 插件的较新版本（8.2.x）里可用。想看到它会执行什么命令，加上 -n 只打印不执行。它的运行记录在 /var/log/omv-compose-run.log。没有这个命令时，用 docker logs --tail 100 <容器名>。

3. 检查 compose 文件

在 文件 页选中该栈，点检查（Check），它会检查 compose 文件的语法。在 shell 里：

# 在 OMV 的 shell 里执行（只读）
omv-compose-run <栈名> config

常见问题：

• YAML 的缩进、冒号和制表符写错。
• 引用了没有定义的变量。
• 示例文件里用到的占位符 CHANGE_TO_COMPOSE_DATA_PATH 没有被替换：这说明你还没有在 服务 → Compose → 设置（Services → Compose → Settings）里指定「数据」共享文件夹，路径会指向不存在的位置。
• 写法细节见写好 compose 文件：卷、端口、环境变量与网络。

4. 按报错类型处理

报错或现象	原因	处理
port is already allocated、address already in use	端口冲突	见端口冲突
no such file or directory（挂载路径）	主机上的目录不存在。用短写法挂载时，Docker 会自动建出一个 root 属主的空目录	先在数据盘上建好目录并设好权限，路径写法见写好 compose 文件
日志里有 permission denied	容器进程的用户对挂载的目录没有写权限	见容器权限：PUID、PGID 与共享文件夹
pull access denied、manifest unknown、not found	镜像名或标签写错，或需要登录私有仓库	核对镜像名和标签；私有仓库在 服务 → Compose → 源（Repos）里登录
toomanyrequests、TLS handshake timeout、i/o timeout，拉取很慢	镜像仓库限流，或 NAS 的网络、DNS 有问题	稍后再试；先确认 NAS 能访问镜像仓库，见更新失败与软件源报错里的网络检查
exec format error	镜像的 CPU 架构与 NAS 不匹配，例如在 arm64 设备上用了 amd64 的镜像	换成支持你架构的镜像，uname -m 能看到你的架构
Exited (137)	通常是内存不足，进程被杀	用 free -h 看内存，用 journalctl -k -b 在内核日志里找 Out of memory 的记录；减少同时运行的容器
Exited (1) 或反复崩溃	应用自己的配置错误：连不上数据库、缺环境变量、配置文件损坏	读日志，再读该应用的官方文档
应用依赖另一个容器（数据库）还没就绪	启动顺序问题	在 compose 里用 depends_on 配合健康检查，并设置重启策略

5. 重建容器

确认了数据位置（见上面的警告）之后：

1. 对该栈点下线（Down），再点上线（Up），容器会按 compose 文件重新创建。
2. 更新了镜像或标签，先点拉取（Pull），再点上线。
3. 仍然不行，在日志里找第一条错误，而不是最后一条。后面的往往只是连带的结果。

6. Docker 引擎本身

在 服务 → Compose → 设置 页面底部，Docker 信息一栏显示状态、Docker 版本、Compose 版本。页面上还有重启 Docker、重新安装 Docker、清除缓存几个按钮。在 shell 里：

# 在 OMV 的 shell 里执行（只读）
systemctl status docker --no-pager
journalctl -u docker -b --no-pager | tail -n 40

Docker 起不来，常见原因是 Docker 存储所在的磁盘没挂载或者已满，或者 /etc/docker/daemon.json 有问题，见Compose 插件设置详解和系统盘满了。

确认恢复

1. 文件 页里该栈的状态是「上线」，docker ps 里 STATUS 以 Up 开头，并且没有在反复重启。
2. 应用的页面能正常访问，日志里没有新的错误。
3. 数据还在：打开应用确认之前的数据可见。
4. 重启 NAS 一次，确认它能自动起来，见重启后容器没起来。

仍未解决

附上：compose 文件（删掉密码、令牌）、docker ps -a 的输出、omv-compose-run <栈名> logs --tail 100 的输出、服务 → Compose → 设置 页的 Docker 信息，以及 uname -m 的结果。分享前去掉密码和令牌，读如何有效求助。

参考资料

• omv-extras wiki：Docker in OMV、Utilities, Maintenance and Backup
• 本站：部署第一个应用、安装 Docker 与 Compose 插件