Docker容器故障排查：常见启动问题与解决方案

当Docker容器无法启动时，最快的修复方法通常来自克制猜测的冲动。容器本质上是一个带有文件系统、环境变量、网络设置和资源限制的进程。如果该进程退出，Docker会记录原因。你的任务是按正确顺序收集证据。

我通常从三个问题入手：Docker是否创建了容器？主进程是否启动？是否有外部因素终止或阻止了进程？这三个问题能区分镜像名称错误与命令错误、端口冲突与应用崩溃、权限问题与内存限制。

从能告诉你真相的基础命令开始：

docker ps -a

查看STATUS、PORTS和NAMES列。Created表示Docker创建了容器但未实际运行。Exited (1)通常表示应用返回了常规错误。Exited (127)通常指向命令缺失。Exited (137)常表示进程被外部终止，通常因内存压力导致。这些退出码是线索而非最终答案，但能避免你在错误层面进行调试。

然后查看日志：

docker logs --tail 100 <容器>
docker logs -f <容器>

如果容器立即退出，docker logs通常比重新运行docker run命令更有用。应用框架通常会在退出前打印出缺失的环境变量、迁移失败、无效配置文件或绑定错误的具体信息。

要查看底层状态，检查容器：

docker inspect <容器> --format '{{json .State}}'
docker inspect <容器> --format 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}} error={{.State.Error}}'

第二个命令值得记住。它能告诉你Docker是否检测到OOM终止、记录的退出码是什么，以及运行时本身是否有错误。

如果容器立即退出

容器只在主进程存活期间保持运行。如果命令执行完毕，Docker会停止容器。当人们运行在后台启动守护进程然后返回的脚本时，这常常让人意外。

例如，这种模式经常导致退出：

CMD service nginx start

service命令可以启动nginx然后结束。Docker看到主进程结束就会停止容器。容器友好的模式是以前台方式运行服务器：

CMD ["nginx", "-g", "daemon off;"]

同样的原则适用于Node、Python、Java和工作进程。CMD或ENTRYPOINT中的命令应该是长期运行的进程，而不是启动后台任务后就退出的启动器。

如果日志显示command not found、no such file or directory或exec format error，以交互方式测试镜像：

docker run --rm -it --entrypoint sh <镜像>

某些镜像不包含bash，特别是Alpine和distroless风格的镜像。除非你知道bash存在，否则先使用sh。进入容器后，检查文件路径、权限和解释器：

ls -l /app
which python || true
head -1 /app/start.sh

脚本可能存在但仍然因no such file or directory失败，如果它的shebang指向缺失的解释器，例如在只有/bin/sh的镜像中使用#!/bin/bash。另一个常见原因是Windows换行符。如果shell脚本在Windows上编辑过，不可见的\r字符会让Linux寻找/bin/sh\r。

如果Docker提示端口已被占用

端口冲突发生在宿主机侧。在-p 8080:80中，8080是宿主机端口，80是容器端口。如果宿主机端口8080上已有进程监听，Docker无法绑定。

你可能会看到类似bind: address already in use或port is already allocated的错误。查找监听进程：

sudo lsof -i :8080
# 或
sudo ss -ltnp 'sport = :8080'

在macOS上，lsof通常最方便。在Linux服务器上，ss通常默认可用。在Windows PowerShell中，使用：

Get-NetTCPConnection -LocalPort 8080

然后选择不同的宿主机端口或停止占用该端口的服务：

docker run -d -p 8081:80 nginx

除非容器内的应用实际监听新端口，否则不要更改容器端口。如果nginx在容器内监听80端口，-p 8081:80是正确的。如果容器内没有进程监听8081，-p 8081:8081会导致浏览器访问失败。

如果应用启动但找不到配置

许多启动失败是由于缺少环境变量。镜像本身没问题，命令也没问题，但应用需要DATABASE_URL、REDIS_URL、API密钥或配置文件。

检查Docker传递了哪些环境变量：

docker inspect <容器> --format '{{range .Config.Env}}{{println .}}{{end}}'

对于Compose项目，检查解析后的配置而不仅仅是docker-compose.yml：

docker compose config

这能捕获缩进错误、.env文件意外情况和展开为空字符串的变量。一个真实案例：DATABASE_URL=${DATABASE_URL}看起来无害，但如果shell或.env文件未定义它，你的应用可能会收到空值并在启动时失败。

注意日志和终端历史中的敏感信息。对于快速本地调试，传递-e NAME=value是可以的。对于共享系统，请使用平台的密钥机制或具有受控权限的环境文件。

如果绑定挂载或卷导致权限错误

容器可能因无法读取配置文件、写入PID文件、创建缓存目录或初始化数据库目录而在启动时失败。日志通常显示permission denied、read-only file system或operation not permitted。

首先检查挂载：

docker inspect <容器> --format '{{json .Mounts}}'

然后检查容器运行的用户：

docker inspect <容器> --format 'user={{.Config.User}}'

如果user为空，镜像可能默认以root运行，但许多生产镜像设置了非root用户。由你本地UID拥有的宿主机目录可能无法被容器内的UID 1000、1001或服务特定用户写入。

一个实用的调试序列是：

ls -ld ./data
docker run --rm -it -v "$PWD/data:/data" --entrypoint sh <镜像>
id
ls -ld /data
touch /data/test

避免用chmod 777解决所有权限问题。它可能掩盖当前问题同时制造更严重的问题。更推荐匹配所有权或使用命名卷存储应用数据：

docker volume create app_data
docker run -d -v app_data:/var/lib/app <镜像>

命名卷在Docker Desktop上特别有用，因为绑定挂载会跨越虚拟化边界，行为可能与原生Linux文件系统不同。

如果容器因内存被终止

退出码137强烈暗示进程收到了SIGKILL。在Docker工作中，这通常意味着内核或Docker Desktop因内存耗尽而终止了进程。通过inspect确认：

docker inspect <容器> --format 'exit={{.State.ExitCode}} oom={{.State.OOMKilled}}'

如果OOMKilled为true，你有两个任务：给进程足够的内存启动，并理解为什么需要这么多内存。对于数据库或JVM服务，提高限制可能是正确的生产修复。对于小型Web服务，这可能暴露了糟糕的默认配置。

Java应用是典型例子。旧版JVM行为并不总能很好地适应容器限制，即使现代JVM仍需要合理的-Xmx或基于百分比的设置来实现可预测的行为。Node服务在内存受限环境中可能需要--max-old-space-size。数据库可能需要显式的缓存设置。

对于一次性测试：

docker run --memory=1g <镜像>

如果你使用Docker Desktop，还要检查分配给Docker VM的内存。如果VM本身资源不足，容器限制也无济于事。

如果镜像从未拉取或构建从未产生镜像

有时没有容器问题，因为没有可用的镜像。如果docker run在创建容器之前失败，请单独验证镜像：

docker image ls | grep my-app
docker pull my-registry/my-app:tag

对于私有仓库，确认身份验证：

docker login <仓库>

对于本地镜像，确保你运行的标签就是你构建的标签：

docker build -t my-app:dev .
docker run --rm my-app:dev

一个常见的本地错误是构建my-app:dev但运行my-app:latest，后者可能指向旧镜像或根本不存在。

如果网络被指责但服务并未监听

当浏览器无法访问容器时，人们常常直接跳到Docker网络问题。首先证明应用在容器内部正在监听。

docker exec -it <容器> sh
ss -ltnp || netstat -ltnp

如果应用在容器内绑定到127.0.0.1，Docker端口发布将无济于事。应用必须监听0.0.0.0或容器的接口地址。这在开发服务器中很常见。例如，许多框架默认监听localhost，需要--host 0.0.0.0这样的标志。

然后确认已发布的端口：

docker port <容器>
docker ps --format 'table {{.Names}}	{{.Ports}}'

你应该看到类似0.0.0.0:8080->3000/tcp的信息。如果没有已发布的端口，服务可能在同一网络的其他容器中工作，但无法从宿主机浏览器访问。

可靠的启动检查清单

当你卡住时，按此顺序操作：

docker ps -a 查看容器是否存在以及如何退出。
docker logs --tail 100 <容器> 读取应用自身的错误信息。
docker inspect <容器> 检查退出码、OOM状态、命令、用户、挂载和端口。
docker run --rm -it --entrypoint sh <镜像> 手动测试镜像。
一次移除一个变量：先不带挂载运行，然后不带自定义网络，最后只带必需的环境变量。

最后一步很重要。一个带有端口、卷、环境文件、自定义DNS、内存限制和自定义入口点的长docker run命令会给你太多嫌疑对象。精简到镜像能启动，然后逐个添加设置直到它崩溃。你刚刚添加的设置通常就是真正问题所在。