docker-troubleshooting

Docker 故障排查 — 问题排查与调试

系统地诊断并解决常见的 Docker 问题。

适用场景

用户提到以下内容时，始终使用此技能：

• “docker 排查”、“docker debug”、“容器问题”
• “容器启动失败”、“exit code”、“crash”
• “OOM”、“磁盘满”、“disk full”
• “网络不通”、“network issues”
• “docker daemon”、“daemon not running”

诊断框架

1. Check container state    → docker ps -a, docker inspect
2. Check logs               → docker logs --tail 100
3. Check resources          → docker stats, docker system df
4. Check exit code          → docker inspect --format='{{.State.ExitCode}}'
5. Interactive debug        → docker run --rm -it image sh

容器启动失败

退出码参考

代码	含义	操作
0	成功	—
1	应用错误	检查 docker logs
125	Docker 守护进程错误	检查守护进程状态
126	无法执行命令	检查权限
127	未找到命令	检查 CMD/ENTRYPOINT 路径
137	SIGKILL（OOM 或 docker kill）	检查内存限制
139	SIGSEGV（段错误）	应用程序错误
143	SIGTERM（正常停止）	健康检查超时？

# Quick diagnosis
docker ps -a | grep Exited
docker inspect --format='{{.State.ExitCode}} {{.State.Error}}' container
docker logs container

磁盘空间耗尽

# Check disk usage
docker system df

# What's using space?
docker system df -v   # Verbose breakdown

# Clean up
docker system prune -a     # Remove all unused: images, containers, volumes, networks
docker image prune -a      # Unused images only
docker volume prune        # Unused volumes only

# Log rotation (prevent future issues)
docker run --log-opt max-size=10m --log-opt max-file=3 myapp

OOM（内存不足）

# Check if container was OOM-killed
docker inspect --format='{{.State.OOMKilled}}' container

# Check memory usage
docker stats --no-stream

# Solution: increase memory limit
docker update --memory=1g --memory-swap=1g container

网络连接

# Check network configuration
docker network inspect bridge
docker exec container ip addr show
docker exec container ping other-container

# DNS check
docker exec container nslookup other-container
docker exec container cat /etc/resolv.conf

# Host networking check
iptables -t nat -L DOCKER -n   # Port forwarding rules

权限问题

# Bind mount permission denied
# Solution 1: Match UID
docker run -u $(id -u):$(id -g) -v $PWD:/app myapp

# Solution 2: Fix permissions in entrypoint
# In entrypoint script: chown -R appuser:appgroup /data

# Docker socket permission
sudo usermod -aG docker $USER   # Add user to docker group
newgrp docker                    # Refresh group (or re-login)

工作流 — 排查流程

步骤 1：查看状态：docker ps -a → 确认退出码和 OOMKilled
步骤 2：查看日志：docker logs --tail 100 <container> 获取错误信息
步骤 3：深入检查：docker inspect → 检查网络/挂载/资源限制
步骤 4：交互式调试：docker run -it --rm --entrypoint sh <image> 进入容器排查
步骤 5：排查资源：使用 docker stats + docker system df 检查 CPU/内存/磁盘

注意事项 — 常见陷阱

• docker system prune 具有破坏性：会移除所有未使用的对象。不要在生产环境中盲目运行。→ 恢复方法：先使用 docker system df 预览；添加 --filter "until=24h" 安全清理；未经确认，切勿运行 prune -a。
• 日志会悄无声息地占满磁盘：JSON-file 驱动程序默认不启用日志轮转。高频输出的应用可能在几小时内占满磁盘。→ 恢复方法：docker run --log-opt max-size=10m --log-opt max-file=3 app；对于现有容器：truncate -s 0 $(docker inspect -f '{{.LogPath}}' myapp)。
• OOMKilled=TRUE，但日志中没有错误：SIGKILL 无法写入日志。→ 恢复方法：检查 docker inspect -f '{{.State.OOMKilled}}' myapp；增加内存：docker update --memory 512m myapp。
• Exited (0)，但服务无法正常工作：应用已启动，但在健康检查通过后崩溃。→ 恢复方法：运行 docker logs --tail 100 myapp；检查应用是否监听 0.0.0.0（而非 127.0.0.1）；使用 docker exec myapp netstat -tlnp 验证。

范围 — 能力边界（适用与不适用场景）

分类	场景	说明
✅ 能做	容器启动失败排查	退出码分析 + docker logs + inspect
✅ 能做	磁盘/日志/资源问题	docker system df + prune + 日志轮转
✅ 能做	OOM/CPU 排查	docker stats + --memory 限制 + OOMKilled
⚠️ 需条件	网络包级分析	需要 tcpdump/Wireshark + 网络知识
⚠️ 需条件	内核级问题	需要 Linux 内核调试技能
❌ 超范围	应用代码 bug 修复	由开发者修复代码
❌ 超范围	生产环境部署	使用 docker-production
❌ 超范围	安全漏洞修复	使用 docker-security + docker-scout

不适用此技能的场景

❌ 跳过	✅ 改用
设置生产环境	docker-production
安全问题	docker-security
性能调优	docker-run（资源限制）
Docker 基础知识	docker-basics

安全与稳定性

• 使用 docker exec 进入生产容器可能会暴露敏感数据。优先使用基于日志的调试方式。
• docker system prune -a 会移除所有未使用的镜像和卷——在生产环境中谨慎使用。
• 使用 --privileged 调试工具检查容器可能会绕过安全控制。
• 切勿为了调试而向容器暴露 Docker 套接字（/var/run/docker.sock）——这会授予 root 访问权限。
• 轮转调试日志——其中可能包含敏感信息。使用带有 TTL 的日志驱动程序。

📚 官方文档参考

文档	地址
Docker 引擎故障排查	https://docs.docker.com/engine/troubleshoot/
docker logs 命令	https://docs.docker.com/reference/cli/docker/container/logs/
docker inspect	https://docs.docker.com/reference/cli/docker/inspect/
Docker CLI 参考	https://docs.docker.com/reference/cli/docker/
守护进程配置	https://docs.docker.com/reference/cli/dockerd/
常见问题 FAQ	https://docs.docker.com/faq/

🧭 Docker Skills Journey

📍 You are here: docker-troubleshooting — 问题排查

← Previous: docker-production