Linux Docker容器启动失败排查方法

Linux Docker容器启动失败往往并非Docker自身故障，而是由退出码误导、日志沉默、挂载路径权限错配、UID不一致、SELinux标签冲突、端口占用、磁盘空间不足或OOMKilled等宿主机层面问题导致；掌握docker ps -a查状态、inspect抓ExitCode和Error、logs判执行时机、手动shell调试CMD/ENTRYPOINT、比对UID与目录权限、检查端口与磁盘资源等一套组合排查法，才能快速穿透表象，直击根因——毕竟，八成的“启动失败”，其实是容器还没来得及活，就已悄然死去。

容器启动失败，八成不是 Docker 本身的问题，而是退出码、日志、挂载或 UID 匹配没对上。

怎么看容器到底有没有“活过”

别光看 docker ps ——它只显示正在运行的容器。真正要查的是全部状态：

• docker ps -a：重点看 STATUS 列，Exited (1) 表示启动后立刻退出，括号里是退出码，比“失败”二字有用十倍
• docker inspect <容器ID>：盯住 State.ExitCode 和 State.Error 字段，后者有时会直接写明 "OCI runtime create failed: ... setenv: invalid argument"，说明环境变量传入非法（比如 Secret 没 base64 编码）
• 如果 STATUS 是 Created 而非 Exited，说明连进程都没起来，问题出在镜像拉取、volume 路径不存在或 --init 不被底层驱动支持等前置环节

日志为空？说明失败发生在应用启动之前

docker logs <容器ID> 返回空，基本可断定：CMD 或 ENTRYPOINT 命令本身执行失败，根本没走到应用逻辑。

• 常见原因：CMD ["python", "app.py"] 中 app.py 路径错误、权限不可执行、Python 解释器缺失，或用了 shell 形式 CMD sh -c "xxx" 导致 exec 替换失败
• 验证方法：用 docker run -it --rm --entrypoint sh <镜像名> 进去，手动执行原 CMD 命令，看是否报 No such file or directory 或 Permission denied
• 特别注意 Alpine 镜像：默认没有 bash，sh 是 busybox 实现，某些语法不兼容；也常因以非 root 用户运行，却尝试写入 /var/log 等 root-only 目录而静默失败

挂载路径和 UID 不匹配是隐形杀手

日志里出现 Permission denied 或应用一写文件就崩，大概率是宿主机与容器用户身份没对齐。

• 查宿主机路径权限：ls -ld /host/path，看属主 UID；再进容器 id，对比 UID 是否一致
• 典型场景：宿主机目录属于 UID 1001，但容器内应用以 UID 1000 运行，且该目录无 group/o 权限，结果连 open(/host/path/config.yaml) 都失败
• 临时验证：加 --user root 启动容器，若成功，基本锁定 UID 问题；生产环境应改镜像 Dockerfile，用 ARG USER_ID 构建时注入当前用户 UID，并 adduser 创建匹配账户
• SELinux 或 rootless Docker 下，还需确认 :z 或 :Z 标签是否加对，否则上下文标签不匹配也会拒写

端口冲突和磁盘空间不足常被忽略

这两类问题不报错在容器日志里，得跳出容器本身去看宿主机环境。

• 端口被占：启动报 Bind for 0.0.0.0:8080 failed，但 docker logs 里啥也没有。用 lsof -i :8080（Linux/macOS）或 netstat -ano | findstr :8080（Windows）找 PID，再 kill 或换端口
• 磁盘满：Docker 报 Thin Pool has ... free data blocks which is less than minimum required，或容器启动卡住无响应。查 df -h，尤其 /var/lib/docker 所在分区；docker system df 可看镜像/容器/卷占用明细
• OOMKilled：docker ps -a 显示 Exited (137)，配合 dmesg -T | grep -i "killed process" 确认是否被系统 OOM killer 干掉；此时需调高 memory limit，或检查应用内存泄漏

最麻烦的永远不是报错信息明确的 case，而是那些日志沉默、状态模糊、退出码看似合理（比如 Exited (0)）的情况——这时候必须进容器内部，用最原始的方式跑一遍启动命令，把“假设”变成“亲眼所见”。

到这里，我们也就讲完了《Linux Docker容器启动失败排查方法》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！