容器与云原生 / 系统课时
排查容器启动失败
排查容器启动失败
容器一启动就退出或不断重启时,最有效的做法不是反复执行 docker restart,而是依次确认状态、退出码、日志和实际启动命令。按这条链路排查,可以快速区分应用自身退出、启动命令错误、资源终止和 Docker 运行阶段错误。
学习目标
- 用容器状态、退出码和重启次数判断故障发生在哪个阶段
- 结合日志、
.State与实际启动参数定位直接根因 - 核对镜像
ENTRYPOINT、CMD与运行参数,并完成修复验证
先确认容器处于什么状态
先看 docker ps -a,不要只看正在运行的容器。Exited 表示主进程已经结束;Restarting 表示退出后被重启策略再次拉起;Created 常见于容器已创建但启动阶段没有真正进入运行状态。
如果 docker run 自身以 125 退出,优先阅读 Docker 返回的错误,例如端口冲突、挂载路径或运行参数无效。此时问题可能发生在容器主进程启动之前,docker logs 不一定有内容。
按固定顺序缩小范围
推荐的顺序是:状态与退出码 → 标准输出和错误输出 → Docker 记录的运行状态 → 容器实际执行的命令 → 镜像默认启动配置。这样能避免一开始就改镜像或改业务配置,把故障越改越复杂。

下面构造一个确定会以退出码 2 结束的容器,并一次性采集排查信息。首次使用 alpine:3.20 时可能额外出现镜像拉取进度,下方只列与诊断有关的稳定输出:
# 先复现退出,再采集状态、退出码、日志和实际启动命令
docker rm -f startup-fail >/dev/null 2>&1 || true
docker run --name startup-fail alpine:3.20 sh -c 'echo "config missing" >&2; exit 2'
docker ps -a --filter name=startup-fail --format 'name={{.Names}} status={{.Status}}'
docker inspect startup-fail --format 'status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}} error={{.State.Error}} restarts={{.RestartCount}}'
docker logs startup-fail
docker inspect startup-fail --format 'path={{.Path}} args={{json .Args}}'
# 镜像默认值要和容器最终执行的 Path/Args 对照看
docker image inspect alpine:3.20 --format 'entrypoint={{json .Config.Entrypoint}} cmd={{json .Config.Cmd}}'预期输出
config missing
name=startup-fail status=Exited (2) <TIME> ago
status=exited exit=2 oom=false error= restarts=0
config missing
path=sh args=["-c","echo \"config missing\" >&2; exit 2"]
entrypoint=null cmd=["/bin/sh"]<TIME> 会随环境变化。关键结论不是状态文本中的时间,而是 exit=2、oom=false,以及日志中的 config missing:这说明 Docker 已经成功启动主进程,失败来自容器内命令主动退出。
用退出码和日志判断根因
退出码只负责缩小范围,不能单独当作最终结论。常见判断可以这样做:0 是正常结束;126 常见于目标存在但不可执行;127 常见于命令不存在;137 表示进程收到 SIGKILL,要继续检查 .State.OOMKilled;143 表示收到 SIGTERM,可能是正常停止流程。
日志用于回答“应用为什么退出”。如果日志为空,再看 .State.Error、挂载、权限、用户、工作目录和启动命令。若应用把日志写入容器内文件而不是标准输出,docker logs 也可能看不到,需要按应用自身的日志路径继续检查。
核对镜像启动配置
镜像的 ENTRYPOINT 决定主程序,CMD 提供默认命令或默认参数;运行 docker run IMAGE ... 时,额外参数通常会替换镜像的 CMD,而 --entrypoint 会覆盖镜像的 ENTRYPOINT。排查时同时看镜像默认值和容器最终的 .Path、.Args,才能知道实际执行了什么。
常见错误包括:镜像里脚本没有执行权限、ENTRYPOINT 指向不存在的文件、脚本使用了镜像中不存在的解释器、工作目录变化导致相对路径失效,以及运行命令把原本必需的 CMD 参数覆盖掉。
修复后做闭环验证
修复不能只以“命令不报错”为准,还要确认容器保持运行、退出码不再异常,并且应用给出健康信号。下面把失败命令改为持续运行 30 秒,并验证状态:
# 修复后确认容器保持运行,并检查应用启动信号
docker rm -f startup-fail
docker run -d --name startup-ok alpine:3.20 sh -c 'echo ready; sleep 30'
docker inspect startup-ok --format 'status={{.State.Status}} exit={{.State.ExitCode}}'
docker logs startup-ok
docker rm -f startup-ok预期输出
startup-fail
<ID>
status=running exit=0
ready
startup-ok运行中的容器显示 exit=0 只是当前状态字段,并不表示它已经退出成功;真正的验收条件是 status=running,并结合应用日志、健康检查或实际服务请求确认业务已经可用。