Docker 容器启动失败排查指南

Docker 容器启动失败时，最重要的是先看状态和日志，不要反复重启。容器退出通常会留下退出码、标准输出、错误日志和事件记录。按顺序查，能很快定位是端口、配置、权限、镜像还是资源问题。

📦 先看容器状态和退出码

docker ps 只显示正在运行的容器，排查失败要用 docker ps -a。重点看 STATUS、Exited 后面的时间和退出码。

  # 查看所有容器状态
docker ps -a

# 查看退出码、启动命令和挂载
docker inspect 容器名

# 只看退出码
docker inspect 容器名 --format '{{.State.ExitCode}}'

# 查看最近事件
docker events --since 30m

📜 看日志：docker logs 是第一现场

容器内程序输出到 stdout/stderr 的内容会进入 docker logs。大多数启动失败都能在这里看到原因。

  # 查看容器日志
docker logs 容器名
docker logs --tail 200 容器名
docker logs -f 容器名

# Compose 服务日志
docker compose logs 服务名
docker compose logs --tail 200 -f

🔌 端口冲突和端口映射错误

端口冲突最常见的报错是 bind: address already in use。说明宿主机端口已经被别的进程或容器占用。

  # 查看端口映射
docker ps --format "table {{.Names}}\t{{.Ports}}"

# 查看宿主机端口占用
sudo ss -lntp | grep -E ':(80|443|3000|8080)\\b'

# 示例：把宿主机 8080 映射到容器 80
docker run -p 8080:80 nginx

• -p 8080:80 表示宿主机 8080 转发到容器内 80。
• 如果容器内应用监听 3000，却映射到 80，访问就会失败。
• 多个容器不能同时占用同一个宿主机端口。

⚙️ 环境变量和配置文件错误

数据库地址、密码、域名、端口、时区和密钥经常通过环境变量传入。变量缺失时，容器可能启动后立刻退出。

  # 查看容器环境变量
docker inspect 容器名 --format '{{range .Config.Env}}{{println .}}{{end}}'

# Compose 中检查最终配置
docker compose config

# 如果使用 .env，确认文件路径和变量名
cat .env

💾 数据卷权限和路径挂载问题

挂载目录不存在、权限不对、宿主机路径写错，会导致应用无法写入配置、数据库或上传文件。

  # 查看挂载
docker inspect 容器名 --format '{{json .Mounts}}'

# 检查宿主机目录
ls -ld /path/to/data
ls -la /path/to/data

# 按应用要求调整权限，示例仅供参考
sudo chown -R 1000:1000 /path/to/data
sudo chmod -R u+rwX /path/to/data

🌐 镜像拉取和网络问题

如果卡在拉镜像，先区分是 Docker Hub 访问慢、DNS 问题，还是镜像名/标签不存在。

  docker pull nginx:latest
docker pull mysql:8.0

# 查看 Docker DNS 和代理配置
docker info

# 临时测试 DNS
nslookup registry-1.docker.io
ping registry-1.docker.io

🧱 Docker Compose 排查流程

Compose 的问题经常来自缩进、变量替换、网络名、depends_on 误解和数据卷路径。先让 Compose 输出合并后的配置。

  # 检查 Compose 配置合并后的结果
docker compose config

# 重新创建服务
docker compose up -d --force-recreate

# 拉取镜像
docker compose pull

# 查看服务状态
docker compose ps

📈 资源不足和 OOM

小内存 VPS 上跑数据库、搜索、面板和多个容器时，容器可能被系统杀掉。退出码 137、系统日志中的 OOM killer 是典型信号。

  free -h
df -h
docker stats
sudo dmesg -T | grep -i -E 'killed process|out of memory|oom'

❓ 常见问题解答