故障排查手册

容器启动失败

退出码速查：0 正常退出 1 应用错误 137 OOM 139 段错误

• 容器是否在运行？ docker ps -a
• 否 → 查看退出码 docker inspect <容器> --format '{{.State.ExitCode}}'
• 0 → 命令执行完就退出了，用 -it 或 tail -f /dev/null 保活
• 1 → 应用报错，查看日志 docker logs <容器>
• 137 → OOM Killed，增加内存 docker run --memory=512m
• 139 → 段错误，检查应用是否兼容容器环境
• 是但无法访问 → 检查端口映射 docker port <容器>
• 端口正确 → 检查应用是否监听 0.0.0.0 而非 127.0.0.1

网络不通

• 容器间能否通信？ docker exec app ping db
• 否 → 是否在同一自定义网络？ docker network inspect mynet
• 不在同一网络 → 加入同一网络 docker network connect mynet app
• 在同一网络 → 检查 DNS 解析 docker exec app nslookup db
• 宿主机能否访问容器？ curl localhost:8080
• 否 → 检查端口映射 docker ps --format "table {{.Names}}\t{{.Ports}}"
• 外部能否访问？
• 否 → 检查防火墙 sudo firewall-cmd --list-ports
• 否 → 检查绑定地址是否为 0.0.0.0 而非 127.0.0.1

存储问题

• Volume 挂载是否正确？ docker inspect <容器> --format '{{.Mounts}}'
• 挂载路径不存在 → 先在宿主机创建目录 mkdir -p /opt/data
• 磁盘是否满了？ df -h
• 满了 → 清理 Docker 资源 docker system prune -a
• 文件权限是否正确？ ls -la /opt/data
• 权限不对 → 调整属主 sudo chown -R 1000:1000 /opt/data
• SELinux 环境 → 加 :z 后缀 -v /opt/data:/app/data:z

构建失败

• Dockerfile 语法错误？ 查看构建输出中的 ERROR 行
• 网络超时 → 检查镜像加速器 docker info | grep -A5 "Registry Mirrors"
• 层缓存失效 → 清理构建缓存 docker builder prune
• npm/pip 安装失败 → 检查网络和源配置
• Alpine 编译失败 → 换用 slim 镜像或安装编译依赖

Compose 编排问题

• 服务启动顺序问题？ 使用 depends_on + healthcheck
• 健康检查失败？ docker compose ps 查看状态
• 查看健康检查日志 docker inspect <容器> --format '{{.State.Health}}'
• 环境变量未生效？ 检查 .env 文件和 environment 优先级
• 端口冲突？ docker compose down 后修改端口再 docker compose up -d