启动失败先按配置、路径、权限、端口、依赖排查，不要先猜镜像坏了。

\n
容器启动失败时，最容易做错的事是马上删目录、换镜像、重建项目。HomeLab 里大多数启动失败并不是镜像坏了，而是配置写错、端口冲突、路径不存在、权限不对、依赖服务没起来，或者应用自己初始化失败。排查顺序固定下来，能少走很多弯路。

第一步看配置是否能展开

先跑 docker compose config。这一步能发现缩进错误、环境变量为空、端口格式不对、挂载路径写错、服务名引用异常。很多问题还没到 Docker 创建容器那一步，配置展开就已经能暴露。尤其是 .env 变量，肉眼看 compose 文件很容易漏，展开后才知道实际路径和端口是什么。

如果配置展开结果里出现意料之外的空字符串、相对路径落点不对、端口不是自己以为的值，就先修配置。不要在配置还不确定时反复 up -d，这样只会产生更多临时容器、空目录和误导日志。

创建失败和启动后退出要分开

容器创建失败，通常看 Docker 层错误：端口已被占用、挂载源不存在、权限不足、镜像拉取失败、网络不存在。容器创建成功但马上退出，才重点看应用日志和退出码。把这两类问题混在一起，会浪费很多时间。

我会先看 docker compose ps 和 docker inspect <container> --format '{{json .State}}'。如果有 ExitCode、OOMKilled、Error 字段，就先记录下来。内存不足、命令找不到、配置文件语法错误、应用迁移失败，都会留下不同线索。面板里一句“启动失败”不够，需要回到 Docker 状态和日志。

端口冲突很常见

端口冲突是 HomeLab 高频问题。旧服务没停、面板占用、系统服务监听、另一个测试容器忘了删，都可能让新容器无法绑定端口。遇到 port is already allocated，不要改一个随机端口就完事。先查谁占用了端口，再决定是停止旧服务、修改端口表，还是调整入口策略。

端口能绑定也不代表能访问。宿主机防火墙、NAS 面板规则、反向入口配置都可能挡住流量。排查访问失败时，按容器内、宿主机、本机浏览器、局域网其他设备的顺序测，能快速判断问题在哪一层。

路径和权限要一起看

挂载路径不存在时，有些情况下 Docker 会自动创建空目录，导致服务以为是首次启动。旧数据没有丢，但应用看不到，页面就像全新安装。遇到升级后配置消失、账号丢失、数据为空，先检查实际 Mounts，而不是急着恢复备份。

权限问题也要用数字看。容器用户是否能写配置目录，宿主机目录属主是否匹配，父目录是否有执行权限，文件系统是否只读，这些都会影响启动。日志里出现 permission denied 时，不要直接放宽整个项目目录，先定位具体文件和运行用户。

镜像和依赖最后再判断

镜像拉取失败、架构不匹配、标签不存在当然也会导致启动失败，但它们通常有明确错误。只有在配置、端口、路径、权限都确认无误后，我才会怀疑镜像版本问题。对于依赖数据库、缓存或其他服务的应用，还要确认依赖是否健康，连接地址是否使用服务名而不是宿主机旧地址。

升级后启动失败尤其要注意数据库迁移。应用可能需要更长初始化时间，也可能因为跨版本太大而失败。此时最重要的是保留现场：不要删数据目录，先备份当前状态，记录旧版本、新版本和第一条错误日志，再决定回滚还是按官方迁移路径处理。

固定排查顺序

我的顺序是：配置展开，镜像是否存在，端口是否冲突，挂载是否正确，权限是否匹配，依赖是否健康，容器状态，应用日志，最近变更。每一步只回答一个问题。处理完后把根因写回维护记录，例如“端口被旧测试服务占用”或“迁移后 data 目录属主仍是旧 uid”。下次再遇到启动失败，就不用从头猜。

还有一种情况是容器能启动，但健康检查一直失败。这时不要只看 running 状态，要看 healthcheck 命令、应用监听地址和启动耗时。有些服务首次初始化需要几分钟，健康检查阈值太短会误判；也有些服务只监听 127.0.0.1，导致容器内检查通过、外部访问失败。状态字段要和真实访问一起看。

排查结束后不要忘了清理现场。临时改过的端口、临时创建的空目录、为了测试拉下来的镜像，都要处理掉。否则下一次启动失败时，这些残留会变成新的干扰项。稳定的排障不只是修好当前问题，也包括让环境回到可解释状态。