容器调试

调试正在运行的 Docker 容器和 Compose 服务。涵盖日志查看、exec 进入、网络诊断、资源使用检查、多阶段构建、健康检查，以及常见故障模式。

适用场景

• 容器启动后立即退出或崩溃
• 容器内应用行为与宿主机上不一致
• 容器之间无法通信
• 容器内存或 CPU 占用过高
• 多阶段 Docker 构建产生意外结果
• 健康检查失败
• Compose 服务启动顺序错误或无法连接依赖服务

容器日志

查看与过滤日志

# 最近 100 行日志
docker logs --tail 100 my-container

# 实时跟踪（流式输出）日志
docker logs -f my-container

# 实时跟踪并显示时间戳
docker logs -f -t my-container

# 查看指定时间之后的日志
docker logs --since 30m my-container
docker logs --since "2026-02-03T10:00:00" my-container

# 查看两个时间点之间的日志
docker logs --since 1h --until 30m my-container

# Compose：查看所有服务的日志
docker compose logs -f

# Compose：查看特定服务的日志
docker compose logs -f api db

# 将日志重定向至文件以便分析
docker logs my-container > container.log 2>&1

# 分离 stdout 和 stderr 输出
docker logs my-container > stdout.log 2> stderr.log

检查日志驱动

# 查看容器使用的日志驱动类型
docker inspect --format='{{.HostConfig.LogConfig.Type}}' my-container

# 若使用 json-file 驱动，查找实际日志文件路径
docker inspect --format='{{.LogPath}}' my-container

# 查看日志文件大小
ls -lh $(docker inspect --format='{{.LogPath}}' my-container)

进入容器执行命令（exec）

交互式 Shell

# Bash（最常用）
docker exec -it my-container bash

# 若无 bash（如 Alpine 或 distroless 镜像）
docker exec -it my-container sh

# 以 root 用户身份执行（即使容器默认非 root 运行）
docker exec -u root -it my-container bash

# 指定环境变量后执行
docker exec -e DEBUG=1 -it my-container bash

# 执行单条命令（不进入交互式 Shell）
docker exec my-container cat /etc/os-release
docker exec my-container ls -la /app/
docker exec my-container env

调试已崩溃容器

# 容器已退出？检查退出码
docker inspect --format='{{.State.ExitCode}}' my-container
docker inspect --format='{{.State.Error}}' my-container

# 常见退出码含义：
# 0   = 正常退出
# 1   = 应用程序错误
# 137 = 被终止（OOM 或 docker kill）— 128 + 信号 9
# 139 = 段错误（segfault）— 128 + 信号 11
# 143 = 终止（SIGTERM）— 128 + 信号 15

# 重新启动已停止容器进行调试
docker start -ai my-container

# 或覆盖 entrypoint 启动 Shell
docker run -it --entrypoint sh my-image

# 从已停止容器中复制文件
docker cp my-container:/app/error.log ./error.log
docker cp my-container:/etc/nginx/nginx.conf ./nginx.conf

无 Shell 环境下的调试（distroless / scratch 镜像）

# 使用 docker cp 提取文件
docker cp my-container:/app/config.json ./

# 使用 nsenter 在容器命名空间中获取 Shell（仅 Linux）
PID=$(docker inspect --format='{{.State.Pid}}' my-container)
nsenter -t $PID -m -u -i -n -p -- /bin/sh

# 启动调试容器并共享目标容器的命名空间
docker run -it --pid=container:my-container --net=container:my-container busybox sh

# Docker Desktop：使用 debug 扩展
docker debug my-container

网络

检查容器网络配置

# 显示容器 IP 地址
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' my-container

# 显示全部网络详情（配合 jq 格式化）
docker inspect -f '{{json .NetworkSettings.Networks}}' my-container | jq

# 列出所有网络
docker network ls

# 检查某网络（含所有已连接容器）
docker network inspect bridge
docker network inspect my-compose-network

# 显示端口映射关系
docker port my-container

测试容器间连通性

# 从容器 A 内访问容器 B
docker exec container-a ping container-b
docker exec container-a curl http://container-b:8080/health

# 容器内 DNS 解析情况
docker exec my-container nslookup db
docker exec my-container cat /etc/resolv.conf
docker exec my-container cat /etc/hosts

# 测试端口是否可达
docker exec my-container nc -zv db 5432
docker exec my-container wget -qO- http://api:3000/health

# 若容器内无 curl/ping，可安装或使用调试容器：
docker run --rm --network container:my-container curlimages/curl curl -s http://localhost:8080

常见网络问题

# “Connection refused”（连接被拒绝）——容器间无法通信
# 1. 检查应用是否监听 0.0.0.0，而非 127.0.0.1
docker exec my-container netstat -tlnp
# 若监听地址为 127.0.0.1，请修改应用配置

# 2. 检查容器是否处于同一网络
docker inspect -f '{{json .NetworkSettings.Networks}}' container-a | jq 'keys'
docker inspect -f '{{json .NetworkSettings.Networks}}' container-b | jq 'keys'

# 3. 检查发布端口（published ports）与暴露端口（exposed ports）的区别
# EXPOSE 仅作声明，不会自动发布端口
# 使用 -p host:container 显式发布端口

# “Name not found”（名称未找到）——DNS 无法解析容器名
# 容器名仅在用户自定义网络中支持 DNS 解析，**默认 bridge 网络不支持**
docker network create my-net
docker run --network my-net --name api my-api-image
docker run --network my-net --name db postgres
# 此时 "api" 和 "db" 可相互解析

捕获网络流量

# 在容器内使用 tcpdump
docker exec my-container tcpdump -i eth0 -n port 8080

# 若容器内无 tcpdump，使用 sidecar 容器
docker run --rm --net=container:my-container nicolaka/netshoot tcpdump -i eth0 -n

# netshoot 预装了 tcpdump、curl、nslookup、netstat、iperf 等工具
docker run --rm --net=container:my-container nicolaka/netshoot bash

资源使用情况

实时统计

# 所有容器资源使用情况
docker stats

# 指定容器
docker stats api db redis

# 单次快照（非流式）
docker stats --no-stream

# 自定义格式输出
docker stats --format "table {{.Name}}t{{.CPUPerc}}t{{.MemUsage}}t{{.NetIO}}"

内存分析

# 查看内存限制
docker inspect --format='{{.HostConfig.Memory}}' my-container
# 0 表示无限制

# 检查容器是否因 OOM 被杀掉
docker inspect --format='{{.State.OOMKilled}}' my-container

# 内存使用详情（Linux cgroups）
docker exec my-container cat /sys/fs/cgroup/memory.current 2>/dev/null || 
docker exec my-container cat /sys/fs/cgroup/memory/memory.usage_in_bytes

# 容器内进程内存占用排行
docker exec my-container ps aux --sort=-%mem | head -10
docker exec my-container top -bn1

磁盘使用情况

# Docker 整体磁盘使用情况
docker system df
docker system df -v

# 容器文件系统大小（增量层大小）
docker inspect --format='{{.SizeRw}}' my-container

# 查找容器内大文件
docker exec my-container du -sh /* 2>/dev/null | sort -rh | head -10
docker exec my-container find /tmp -size +10M -type f

# 检查日志文件是否膨胀
docker exec my-container ls -lh /var/log/

Dockerfile 调试

多阶段构建调试

# 构建至指定构建阶段
docker build --target builder -t my-app:builder .

# 检查 builder 阶段内容
docker run --rm -it my-app:builder sh
docker run --rm my-app:builder ls -la /app/
docker run --rm my-app:builder cat /app/package.json

# 检查最终镜像中包含哪些文件
docker run --rm my-image ls -laR /app/

# 不使用缓存构建（全新构建）
docker build --no-cache -t my-app .

# 显示详细构建过程（含每步命令输出）
docker build --progress=plain -t my-app .

镜像检查

# 查看镜像分层（各层大小）
docker history my-image
docker history --no-trunc my-image

# 检查镜像配置（entrypoint、cmd、env、ports 等）
docker inspect my-image | jq '.[0].Config | {Cmd, Entrypoint, Env, ExposedPorts, WorkingDir}'

# 对比两个镜像
docker history image-a --format "{{.Size}}t{{.CreatedBy}}" > layers-a.txt
docker history image-b --format "{{.Size}}t{{.CreatedBy}}" > layers-b.txt
diff layers-a.txt layers-b.txt

# 查看容器自创建以来的文件变更
docker diff my-container
# A = 新增，C = 修改，D = 删除

健康检查

定义与调试健康检查

# 在 Dockerfile 中定义
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 
  CMD curl -f http://localhost:8080/health || exit 1

# 查看健康状态
docker inspect --format='{{.State.Health.Status}}' my-container
# 返回值可能为 "healthy"、"unhealthy" 或 "starting"

# 查看健康检查历史（最近 5 次结果）
docker inspect --format='{{json .State.Health}}' my-container | jq

# 手动执行健康检查命令
docker exec my-container curl -f http://localhost:8080/health

# 运行时覆盖健康检查配置
docker run --health-cmd "curl -f http://localhost:8080/health || exit 1" 
           --health-interval 10s my-image

# 禁用健康检查
docker run --no-healthcheck my-image

Docker Compose 调试

服务启动问题

# 查看服务状态
docker compose ps

# 查看某服务失败原因
docker compose logs failed-service

# 启动并输出详细日志（同时保存到文件）
docker compose up --build 2>&1 | tee compose.log

# 启动单个服务（及其依赖项）
docker compose up db

# 启动单个服务（忽略依赖项）
docker compose up --no-deps api

# 强制重建所有容器
docker compose up --force-recreate --build

# 查看生效的 Compose 配置（含变量替换后结果）
docker compose config

服务依赖与启动顺序

# docker-compose.yml
services:
  api:
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started

  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

# 在运行命令前等待服务就绪
docker compose up -d db
docker compose exec db pg_isready  # 持续轮询直至就绪
docker compose up -d api

清理

# 清理已停止的容器
docker container prune

# 清理未被使用的镜像
docker image prune

# 清理所有未被使用的资源（容器、镜像、网络、卷）
docker system prune -a

# 同时清理卷（警告：将永久删除数据）
docker system prune -a --volumes

# 清理悬空的构建缓存
docker builder prune

提示与技巧

• docker logs -f 是排查问题的第一步。绝大多数容器故障均可通过日志直接定位。
• 退出码 137 表示因 OOM 被系统终止。请增加内存限制或修复内存泄漏问题。
• 容器内应用必须绑定 0.0.0.0，而非 127.0.0.1。容器内的 localhost 是隔离的网络命名空间。
• 容器名仅在用户自定义网络中支持 DNS 解析，**默认 bridge 网络不支持**。多容器部署务必创建自定义网络。
• docker exec 仅适用于正在运行的容器。对于已崩溃容器，请使用 docker cp 提取日志，或通过 docker run --entrypoint sh 覆盖入口点进入调试。
• nicolaka/netshoot 是容器网络调试的瑞士军刀，预装全部常用网络诊断工具。
• 构建时使用 --progress=plain 可显示完整命令输出，对排查构建失败至关重要。
• 健康检查中设置 start-period 可避免应用启动较慢时误报“unhealthy”状态。