Docker 排障：构建、退出、网络与存储 · Docker 故障排查

Docker 排障：构建、退出、网络与存储

Docker 故障排查

1. 原则与现场

先确认 host、Context、项目、容器和时间范围；先采集再重启/清理，一次只改一个变量。

bash

date -Is
docker context show
docker version
docker ps -a --no-trunc
docker system df -v
sudo journalctl -u docker --since '30 min ago' --no-pager

容器现场：

bash

docker inspect CONTAINER
docker logs --since 30m --timestamps CONTAINER
docker stats --no-stream CONTAINER

输出可能含环境变量、地址和挂载，对外发送前脱敏。

2. Daemon 无法连接

bash

docker context ls
printf '%s\n' "${DOCKER_HOST:-unset}"
ls -l /var/run/docker.sock
sudo systemctl status docker --no-pager
sudo journalctl -u docker -n 200 --no-pager
sudo dockerd --validate --config-file=/etc/docker/daemon.json

检查 Context、daemon 状态、socket 权限、配置、磁盘和证书。不要用 chmod 666 socket 绕过权限问题。

3. 容器退出或重启

bash

docker logs --tail 200 api
docker inspect api \
  --format 'status={{.State.Status}} exit={{.State.ExitCode}} error={{.State.Error}} oom={{.State.OOMKilled}}'
docker inspect api \
  --format 'entrypoint={{json .Config.Entrypoint}} cmd={{json .Config.Cmd}}'

退出码 125/126/127 常指 Docker 启动失败、命令不可执行、命令不存在；137 需结合 OOM/信号判断。重启循环时先采集，再临时：

bash

docker update --restart=no api
docker stop api

修复后把正确策略同步回部署清单。

4. 镜像、网络与 DNS

bash

docker buildx imagetools inspect IMAGE
docker inspect api --format '{{json .NetworkSettings.Networks}}'
docker network inspect app-net
docker exec api getent hosts db
docker exec api cat /etc/resolv.conf
docker exec api ss -lntup
docker port api
curl -v http://127.0.0.1:8080/healthz

拉取报错时：unauthorized 查身份/scope，manifest unknown 查引用，no matching manifest 查平台，x509 查 CA、链、hostname 和时间。连通性检查同一网络、服务名、端口、监听地址及 VPN 网段冲突。

5. 权限与存储

bash

docker exec api id
docker inspect api --format '{{json .Mounts}}'
docker exec api stat -c '%u:%g %a %n' /app/data
sudo stat -c '%u:%g %a %n' /srv/app/data
df -hT
df -i
sudo du -xhd1 /var/lib/docker | sort -h

修复准确 UID/GID、mode 或 LSM policy；不要 chmod -R 777、关闭 SELinux/AppArmor或直接删除 Docker data-root 内部文件。

6. OOM 与性能

bash

docker inspect api \
  --format 'oom={{.State.OOMKilled}} memory={{.HostConfig.Memory}}'
docker stats --no-stream api
sudo journalctl -k --since '1 hour ago' | grep -i oom

区分泄漏、峰值、限制过低和宿主整体资源不足，提高 limit 前先压测。

7. Compose 与 Build

bash

docker compose config
docker compose ps -a
docker compose logs --since 30m --timestamps
docker buildx inspect --bootstrap
docker buildx build --progress=plain --no-cache .

Compose 核对 -f 顺序、项目名、变量和 profile；Build 本地无镜像时检查 driver 与 --load，exec format error 检查平台。

8. 高风险救援

rm -f、任意 prune、compose down --volumes、删除 data-root、切换存储驱动、重装或大版本升级都不是普通诊断步骤，必须审批、备份并确认影响范围。

9. 官方参考

补充实践：Docker 镜像构建失败

来源：show-cmd；原记录日期：未标注。以下保留来源案例的环境和版本范围。

定位失败层，检查构建上下文、文件复制和依赖安装。

在包含 Dockerfile 的目录执行构建。构建上下文由最后的路径参数决定；COPY 看不到上下文之外的文件，也可能被 .dockerignore 排除。

排查步骤

1. 显示完整构建输出

docker build --progress=plain -t local-debug .

预期结果: 记录失败的 Dockerfile 指令及其原始错误，而不是只看最后一行。

2. 核对上下文与排除规则

ls -la
cat .dockerignore

预期结果: COPY 的源文件位于构建上下文内，且未被 .dockerignore 排除。

3. 仅在怀疑缓存时重新构建

docker build --no-cache --progress=plain -t local-debug .

预期结果: 若失败消失，检查缓存层依赖；若仍失败，回到失败层检查命令和网络。

常见报错

COPY failed / file not found

原因: 源文件不在上下文中或被忽略。

处理方式: 核对最后的构建路径、COPY 相对路径和 .dockerignore。

RUN 命令返回非零退出码

原因: 该层内的依赖安装或编译命令失败。

处理方式: 查看完整输出中的首个具体错误，核对镜像内工作目录、包管理器和网络。

官方资料

补充实践：Docker 容器启动后退出

来源：show-cmd；原记录日期：未标注。以下保留来源案例的环境和版本范围。

用退出码、日志和容器状态区分应用崩溃与配置问题。

容器的主进程结束后容器会停止。先保留失败容器和日志，确认启动命令、环境变量、挂载和资源限制，再决定是否重建。

排查步骤

1. 确认容器与退出状态

docker ps -a --filter name=<container>

预期结果: STATUS 显示退出时间与状态，避免只查看运行中的容器。

2. 读取退出前日志

docker logs --tail=100 <container>

预期结果: 应用日志给出异常、缺少配置或连接失败的具体位置。

3. 核对退出码与 OOM 状态

docker inspect --format '{{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}' <container>

预期结果: OOMKilled 为 true 时优先排查内存；否则结合退出码和日志检查主进程。

常见报错

ExitCode 1

原因: 主进程报告错误并退出。

处理方式: 以 logs 中第一条实际应用错误为起点，核对入口命令和配置。

OOMKilled true

原因: 容器超出可用内存。

处理方式: 检查负载、内存使用和限制，修复内存问题或按容量需求调整限制。

Docker 排障：构建、退出、网络与存储 · Docker 故障排查