容器与云原生 / 系统课时
排查容器启动失败
排查容器启动失败
容器执行 docker run 或 Compose 启动后立刻退出时,不应直接反复重启。本课建立一条可重复的定位路径:先确认状态和退出码,再读日志与启动配置,随后检查文件权限和依赖服务,最后用相同镜像复现并验证修复。
学习目标
- 根据容器状态、退出码和日志判断故障发生在哪个阶段。
- 检查启动命令、环境变量、挂载文件权限和依赖服务是否满足运行条件。
- 使用相同镜像覆盖入口命令进行交互式复现,并验证修复结果。
第一步:确认状态和退出码
启动失败时先不要删除容器,因为已退出容器仍保存着状态、日志和配置。使用 docker ps -a 找到目标容器,再通过 docker inspect 获取退出码、错误信息和是否发生 OOM。下面以名为 web 的容器为例:
docker ps -a --filter name=web
docker inspect web --format 'status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}} error={{.State.Error}}'预期输出
CONTAINER ID IMAGE COMMAND CREATED STATUS NAMES
<ID> myapp:1.0 "<PATH>" <TIME> Exited (1) <TIME> ago web
status=exited exit=1 oom=false error=退出码 0 通常表示进程正常结束,而非零值表示程序或启动脚本报告失败。若 oom=true,优先检查内存限制和宿主机内存压力;若 State.Error 有内容,则更可能是 Docker 在创建或启动容器阶段就遇到了问题。
第二步:读取首个有效错误
日志应紧接状态检查。启动失败时通常最有价值的是进程退出前的第一条明确错误,例如缺失配置文件、端口绑定失败、数据库连接失败或权限不足,而不是后续重复打印的堆栈。
docker logs --tail 100 web预期输出
<TIME> ERROR failed to read configuration: permission denied: <PATH>如果日志完全为空,不代表应用没有问题。进程可能在日志系统初始化之前就失败,也可能入口文件本身无法执行。此时应直接检查容器配置和挂载内容,而不是继续增加日志行数。

第三步:核对启动命令与挂载
日志指向配置或入口问题时,用 docker inspect 查看镜像入口、命令、环境变量和挂载,不要凭 Compose 文件或部署脚本猜测,因为运行中的实际配置可能已经被覆盖。
docker inspect web --format 'entrypoint={{json .Config.Entrypoint}} cmd={{json .Config.Cmd}} mounts={{json .Mounts}}'预期输出
entrypoint=["<PATH>"] cmd=["<PATH>"] mounts=[{"Type":"bind","Source":"<PATH>","Destination":"<PATH>"}]对 bind mount 尤其要检查宿主机源路径是否存在、文件类型是否正确,以及容器进程用户能否读取或执行。常见问题包括把目录挂到预期文件位置、脚本缺少执行权限、配置文件只允许宿主机特定用户读取。宿主机上可以直接检查源文件权限:
ls -ld <PATH>
ls -l <PATH>预期输出
drwxr-xr-x <ID> <ID> <ID> <TIME> <PATH>
-rw-r--r-- <ID> <ID> <ID> <TIME> <PATH>实际用户、组和路径会不同。若容器以非 root 用户运行,还要确认该 UID 或 GID 对挂载内容具备所需权限,而不是简单地把文件改成所有人可写。
第四步:确认依赖服务可达
应用进程能够执行但随后退出,常见原因是启动阶段强依赖数据库、缓存、消息队列或内部 API。日志中出现 connection refused、DNS 解析失败或超时时,应检查依赖服务是否运行、网络名称是否正确,以及应用使用的是容器内可达地址而不是错误的 localhost。
如果目标依赖与应用位于同一个 Docker 网络,可以启动临时容器验证 DNS:
docker run --rm --network <ID> busybox:1.36 nslookup db预期输出
Server: <ID>
Address 1: <ID>
Name: db
Address 1: <ID> db网络名、DNS 地址和解析出的容器地址属于动态值。解析成功只说明名称可解析;若应用仍报告连接失败,还要继续确认服务端口是否监听以及依赖自身是否已完成初始化。
第五步:覆盖入口命令复现
当原进程一启动就退出,可以暂时覆盖入口命令进入镜像内部检查文件、环境变量和可执行权限。这种方法不会修改原镜像,适合验证“镜像里到底有什么”。
docker run --rm -it --entrypoint sh myapp:1.0预期输出
/ #进入后只做针对性检查,例如确认 <PATH> 是否存在、环境变量是否注入、启动文件是否可执行。不要在临时容器里手工修改后就把问题视为已修复,真正的修复应落到 Dockerfile、镜像构建、Compose 配置或部署参数中。
修复后重新验证
完成修复后重新创建容器,并同时确认状态、日志和健康检查。仅看到容器处于 running 还不够,因为进程可能已经启动但应用尚未具备服务能力。
docker ps --filter name=web --format 'table {{.Names}}\t{{.Status}}'
docker logs --tail 20 web预期输出
NAMES STATUS
web Up <TIME> (healthy)
<TIME> application started如果镜像没有配置健康检查,状态中不会出现 healthy,此时应改用应用自身的健康接口或实际业务请求完成验收。