mcpField
T
troubleshoot

troubleshoot

github.com/mwguerra云与 DevOps3637 次安装26 周前更新
代码仓库

关于 troubleshoot

troubleshoot 是帮助排查和处理常见 Docker 问题的技能，面向维护 Docker Compose 服务的开发者与运维人员。它提供诊断命令和对应解决办法，覆盖启动、网络、权限、存储及健康检查等故障。

主要功能

  1. 01诊断容器启动失败
  2. 02排查网络和端口冲突
  3. 03处理权限与数据持久化问题
  4. 04检查健康状态和磁盘空间
  5. 05提供 Docker Compose 排障命令

适用场景

  1. 01定位无法启动的 Compose 容器
  2. 02排查容器间无法连接或端口占用
  3. 03调查数据丢失、权限或健康检查故障

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/mwguerra/claude-code-plugins --skill troubleshoot

安装后在 Claude Code 中输入/troubleshoot确认已加载。

详细介绍

Docker 故障排除技能

概述

此技能可帮助诊断并解决常见的 Docker 问题：

  • 容器启动失败
  • 网络问题
  • 权限错误
  • 端口冲突
  • 数据持久化问题
  • 健康检查失败

流程

1. 查阅文档

阅读相关文档：

  • 17-troubleshooting.md，了解常见问题
  • 15-port-conflicts.md，了解端口问题
  • 16-restart-strategies.md，了解重启问题
2. 诊断问题

收集信息：

# Check container status
docker compose ps -a

# View logs
docker compose logs servicename

# Check configuration
docker compose config

# Inspect container
docker inspect containername
3. 应用解决方案

常见问题及解决方案

容器无法启动

诊断：

docker compose logs servicename
docker inspect --format='{{.State.ExitCode}}' containername

解决方案：

  • 查看日志中的错误消息
  • 验证配置语法
  • 检查依赖项是否正在运行
  • 验证镜像是否存在
端口已被占用

诊断：

lsof -i :3000
# or
netstat -tulpn | grep 3000

解决方案：

# Kill process
kill $(lsof -t -i:3000)

# Or change port in compose
ports:
  - "3001:3000"
权限被拒绝

诊断：

docker compose exec app ls -la /app/data

解决方案：

# Fix in compose
services:
  app:
    user: "1000:1000"

# Or fix in container
docker compose exec -u root app chown -R appuser:appgroup /app/data
数据消失

诊断：

docker volume ls
docker compose config | grep -A5 "volumes:"

解决方案：

# Use named volumes instead of anonymous
volumes:
  - postgres_data:/var/lib/postgresql/data  # Named (persists)
  # NOT: - /var/lib/postgresql/data  # Anonymous (deleted)
容器无法访问其他容器

诊断：

docker network inspect networkname
docker compose exec app ping db
docker compose exec app nslookup db

解决方案：

# Ensure same network
services:
  app:
    networks:
      - backend
  db:
    networks:
      - backend

networks:
  backend:
健康检查失败

诊断：

docker inspect --format='{{json .State.Health}}' containername | jq

解决方案：

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s  # Give time to start
磁盘空间不足

诊断：

docker system df
docker system df -v

解决方案：

# Clean unused resources
docker system prune -a --volumes
构建缓存问题

解决方案：

docker compose build --no-cache
docker builder prune -a

调试命令

# Shell into running container
docker compose exec app sh

# Shell into failed container
docker compose run --entrypoint sh app

# View resource usage
docker stats

# View container processes
docker compose top

# View real-time events
docker events

# Copy files from container
docker compose cp app:/app/logs ./logs

快速诊断清单

  1. 检查容器是否正在运行： docker compose ps
  2. 检查日志： docker compose logs servicename
  3. 检查网络： docker network ls
  4. 检查卷： docker volume ls
  5. 检查资源： docker stats
  6. 验证配置： docker compose config
  7. 检查磁盘空间： docker system df

错误消息参考

错误原因解决方案
"port is already allocated"端口已被占用终止进程或更改端口
"network not found"网络缺失创建网络或检查名称
"volume not found"卷缺失创建卷或检查名称
"no such service"服务名称拼写错误检查 compose.yaml
"unauthorized"身份验证问题docker login
"image not found"镜像缺失docker compose pull
"permission denied"文件权限问题修正所有权/权限
"out of memory"内存限制提高限制或优化应用

评论

支持 Markdown