故障排除：快速诊断常见Docker容器错误

当Docker容器立即退出时，不要一开始就重建镜像或随意更改标志。首先查明Docker已知的信息：容器状态、退出码、日志以及Docker尝试运行的确切命令。这四部分信息通常能快速缩小问题范围。

容器本质上是一个带有隔离机制的进程。如果主进程退出，容器也会退出。这可能是崩溃、可执行文件缺失、批处理任务完成、健康依赖失败，或者内核因内存使用过多而终止进程。以下命令可帮助您区分这些情况。

首先找到已停止的容器

docker ps仅显示运行中的容器。启动失败的容器通常被隐藏，除非您请求查看所有容器：

docker ps -a

查看STATUS、COMMAND和NAMES列：

CONTAINER ID   IMAGE          COMMAND              STATUS                      NAMES
2d3f4b5c6e7a   my-app:latest  "/usr/bin/start"     Exited (127) 2 minutes ago  web-service
91aa34c0db22   worker:latest  "python worker.py"   Exited (0) 10 minutes ago   nightly-worker

Exited (0)通常表示进程成功完成。这对于一次性任务来说是正常的。但对于Web服务，这可能意味着命令运行后即结束，而非保持在前台运行。

非零退出码指向失败，但应将其视为线索而非最终答案。退出码127通常表示命令未找到。126通常表示找到但不可执行。137通常表示进程收到SIGKILL信号；在容器中，这通常（但不总是）与内存压力有关。务必通过日志和inspect输出进行确认。

在更改任何内容之前先读取日志

对于默认的日志驱动，Docker会捕获容器主进程的stdout和stderr。使用：

docker logs web-service

有用的选项：

docker logs --tail 100 web-service
docker logs --since 15m web-service
docker logs -t web-service
docker logs -f web-service

如果日志显示config file not found，请检查挂载和环境变量。如果显示应用程序堆栈跟踪，请调试应用程序。如果日志为空，则进程可能在产生输出之前就已失败，或者镜像入口点设置错误。

对于崩溃循环，避免仅使用docker logs -f。它可能让您感觉故障仍在活跃，但并未提供状态信息。请将日志与docker inspect结合使用。

检查容器状态

docker inspect返回一个大型JSON文档。您通常不需要全部内容。从格式化字段开始：

docker inspect -f 'status={{.State.Status}} exit={{.State.ExitCode}} oom={{.State.OOMKilled}} error={{.State.Error}}' web-service

然后检查命令和镜像配置：

docker inspect -f 'entrypoint={{json .Config.Entrypoint}} cmd={{json .Config.Cmd}} user={{.Config.User}}' web-service

当错误涉及文件时，检查挂载：

docker inspect -f '{{json .Mounts}}' web-service

如果容器因内存被终止，.State.OOMKilled是重要字段。如果为true，增加内存可能有所帮助，但更好的下一步是探究内存增长的原因。更大的限制可能暂时掩盖内存泄漏，但最终仍会失败。

尽可能使用交互式Shell重现问题

如果镜像包含Shell，覆盖入口点并检查文件系统：

docker run --rm -it --entrypoint /bin/sh my-app:latest

某些镜像包含Bash：

docker run --rm -it --entrypoint /bin/bash my-app:latest

在容器内部，检查文件和命令路径：

ls -l /usr/bin/start
id
env

最小化镜像可能不包含Shell。在这种情况下，请使用镜像中可用的工具、重建临时调试变体，或检查Dockerfile和构建输出。不要仅仅因为一次故障排除的不便，就永久地将调试包添加到生产镜像中。

命令未找到：退出码127

退出码127通常表示Docker无法找到ENTRYPOINT或CMD指定的可执行文件，或者启动脚本尝试运行一个缺失的命令。

常见原因：

可执行文件从未被复制到镜像中。
路径在主机上正确，但在镜像内部不正确。
脚本使用/bin/bash，但镜像只有/bin/sh。
命令依赖于PATH，而PATH与您期望的不同。

检查镜像命令：

docker inspect -f '{{json .Config.Entrypoint}} {{json .Config.Cmd}}' web-service

如果入口点是脚本，请检查其shebang和行尾。带有Windows CRLF行尾的脚本可能会因解释器路径包含回车符而失败，并显示令人困惑的“未找到”消息。

权限被拒绝：退出码126或文件错误

退出码126通常表示Docker找到了命令但无法执行。对于脚本，文件可能缺少可执行位：

COPY start.sh /usr/local/bin/start.sh
RUN chmod 0755 /usr/local/bin/start.sh
ENTRYPOINT ["/usr/local/bin/start.sh"]

对于卷挂载的文件，请记住主机权限适用。如果容器以UID 1000运行，而主机目录由root拥有且没有写入权限，则容器无法因为“在Docker内部”而写入该目录。

检查运行时用户：

docker inspect -f 'user={{.Config.User}}' web-service

如果为空，许多镜像默认以root运行，但并非全部。官方和安全加固的镜像通常使用非root用户。

端口已分配

当您发布一个已被使用的主机端口时，通常会出现绑定错误：

docker run -p 8080:80 nginx

Docker可能会报告类似bind: address already in use的信息。查找冲突：

docker ps --format 'table {{.Names}}\t{{.Ports}}'
lsof -iTCP:8080 -sTCP:LISTEN

然后停止冲突的进程或选择另一个主机端口：

docker run -p 8081:80 nginx

容器端口可以保持不变。主机端口是冒号前的部分。

文件缺失和错误挂载

如果日志显示配置文件缺失，请比较应用程序期望的内容与Docker挂载的内容：

docker inspect -f '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}' web-service

一个常见错误是将主机目录挂载到镜像中已有文件的路径上。挂载会隐藏该目标路径下的镜像内容。如果镜像包含/app/config/default.yml，而您将空的主机目录挂载到/app/config，则默认文件将从容器视图中消失。

还要检查相对路径。-v ./config:/app/config取决于您运行docker run的目录，而不是Dockerfile所在的目录。

健康检查失败并不总是容器崩溃

容器可能正在运行但不健康：

docker ps

您可能会看到Up 2 minutes (unhealthy)。检查健康输出：

docker inspect -f '{{json .State.Health}}' web-service

健康检查失败通常是因为应用程序监听不同的端口、仅绑定到127.0.0.1、启动时间超过健康检查允许的时间，或需要尚未就绪的数据库。不要将不健康的容器与已退出的容器混淆；它们的诊断路径不同。

快速故障排除序列

当您需要快速获得答案时，请按此顺序操作：

docker ps -a 查找容器和退出码。
docker logs --tail 100 <name> 读取应用程序错误。
docker inspect -f ... 检查状态、命令、用户和挂载。
如果命令或文件系统可疑，在镜像中运行临时Shell。
检查主机上的端口冲突和挂载目录权限。
仅在确定问题是镜像内容、运行时标志还是应用程序配置后，才进行重建。

该序列确保调查基于事实。Docker通常有足够的证据；关键在于在改变现场之前读取这些信息。

在信任所见之前检查重启策略

重启策略可能使容器看起来要么持续失败，要么持续恢复。检查它：

docker inspect -f 'restart={{json .HostConfig.RestartPolicy}}' web-service

如果策略是always或unless-stopped，Docker可能会在每次崩溃后重启容器。docker ps可能显示它运行了几秒钟，然后又重启。在这种情况下，使用带时间戳的日志并检查重启次数：

docker inspect -f 'restarts={{.RestartCount}} started={{.State.StartedAt}} finished={{.State.FinishedAt}}' web-service

高重启次数通常意味着主进程快速退出。修复方法很少是“更改重启策略”。策略只是揭示了潜在的失败。

区分构建时问题和运行时问题

如果容器内缺少文件，请问它应该何时出现。在Dockerfile中复制的文件是构建时问题。使用-v或Compose卷挂载的文件是运行时问题。

构建时检查：

docker image inspect my-app:latest
docker run --rm --entrypoint /bin/sh my-app:latest -c 'ls -la /app'

运行时检查：

docker inspect -f '{{range .Mounts}}{{println .Source "->" .Destination}}{{end}}' web-service

这种划分节省时间。重建镜像无法修复错误的主机挂载。更改卷标志无法修复从未复制二进制文件的Dockerfile。

环境变量和密钥可能静默失败

许多应用程序因缺少必需的环境变量而退出，但Docker错误仅显示进程以代码1退出。仔细检查配置的环境：

docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' web-service

注意运行该命令的位置；它可能打印密钥。在共享日志中，仅打印变量名称：

docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' web-service | sed 's/=.*//'

如果您使用--env-file，请检查CRLF行尾、未引用的空格和缺失的文件。Docker环境文件不是完整的Shell脚本。保持简单：KEY=value行，在您的Docker版本支持的地方添加注释，并且不要假设文件内会发生Shell扩展。

发布前的真实世界审查

在将脚本或容器设置标记为完成之前，请以凌晨2点需要调试它的下一个人身份阅读一遍。这会改变您的注意点。编写脚本时合理的提示，在CI日志中出现时可能变得模糊。感觉明显的Docker服务名称可能与应用程序中的变量名不匹配。Bash默认值可能对开发安全，但对生产危险。

我喜欢用故意尴尬的值进行简短的试运行。使用带空格的路径。使用空的可选值。尝试以破折号开头的文件名。从不同的工作目录运行脚本。在没有一个预期环境变量的情况下启动容器。这些测试并不花哨，但它们能捕获通常首先失败的假设。

还要检查失败消息。如果唯一的输出是failed，那么文章的建议尚未落实到实现中。有用的失败消息应说明使用了什么值、什么检查失败以及操作员可以更改什么。这并不意味着转储每个环境变量或打印密钥。而是意味着在有助于解决问题的地方具体说明：配置路径、缺失的命令名称、网络名称、服务主机名或进程尝试绑定的端口。

最后一个习惯是让示例贴近系统实际运行的方式。如果生产环境使用Compose，则用Compose测试。如果脚本由systemd启动，则用systemd或类似的最小环境测试。如果命令应该安全地复制粘贴，则在示例中包含引号、--分隔符和验证。读者复制工作模式的频率远高于复制警告。

这个审查过程不是官僚主义。它是让小型自动化保持无趣的方式。无趣正是您对Shell提示、配置加载器、变量扩展、容器诊断和Docker网络所期望的。行为越不令人惊讶，下一个操作员就越容易信任它。

对于Docker故障，尽可能保存创建容器的确切命令。docker inspect可以显示当前配置，但包含原始docker run命令、Compose服务、镜像标签和环境文件名称的事件记录，在后续重现时容易得多。在严肃调试期间避免使用latest。一个变化的标签可能将一个故障变成两个不同的调查，因为您在读取日志时镜像发生了变化。

如果您在本地诊断类似生产环境的问题，请拉取相同的镜像摘要或标签，使用相同的卷布局，并传递相同的非密钥环境形状。重现胜过猜测。