docker Roadmap
Docker / Compose 排障专题
Docker / Compose 排障专题：聚合容器端口映射不通、镜像拉取失败、Compose 配置不生效、磁盘清理与孤儿镜像、容器网络与 DNS、volume 权限等常见问题的完整排障流程与命令模板。
容器问题不要只盯着容器内部，宿主机端口和防火墙、镜像 registry 与代理、network 与 DNS、volume 权限都要一起看，Compose 项目额外看 docker compose config 展开结果和 healthcheck 依赖。
Troubleshooting Path
推荐排障路线图
- 01
先确认容器状态和日志
用 docker ps -a、docker logs、docker inspect 判断是否启动、重启循环或退出。
- 02
再核对端口和监听地址
检查 ports 映射、容器内监听 0.0.0.0 还是 127.0.0.1，以及宿主机防火墙。
- 03
继续检查镜像和网络
镜像拉取失败看 registry、代理、架构；容器互访失败看 network 和 DNS。
- 04
最后检查卷和 Compose 配置
验证 volume 权限、环境变量、depends_on、healthcheck 和 docker compose config 输出。
Before You Change
执行前检查
- 先执行 docker compose config 校验 YAML
- 生产机慎用 docker system prune -a
- volume 路径修改前确认数据备份
- 端口不通时同时查安全组和宿主机防火墙
Start Here
优先阅读
Docker 镜像清理与瘦身
Docker 镜像和构建缓存占满磁盘时，用 docker system df 查看整体占用，按 dangling 中间层、未使用镜像、构建缓存的顺序渐进清理，避免直接 docker system prune -a 误删仍被停止容器引用的镜像。
排障Docker 容器网络不通排查
Docker 容器之间 ping/curl 不通、DNS 无法解析容器名或访问不了宿主机服务时，用 docker network inspect 查看网络成员，确认容器是否在同一自定义 network，Docker 内置 DNS 只在自定义网络生效，宿主机访问用 host.docker.internal。
排障Docker Volume 权限拒绝排查
Docker 挂载卷后容器进程写文件报 permission denied 时，用 docker exec id 查看容器运行用户 UID，对比宿主机目录 owner 和 mode，再决定是 chown 目录还是通过 --user、Dockerfile USER 或 SELinux :Z 调整容器用户匹配宿主机权限。
排障Node.js EADDRINUSE 端口被占用排查
Node.js 启动服务报 Error: listen EADDRINUSE: address already in use :::3000 时，用 lsof -iTCP:3000 -sTCP:LISTEN 或 ss -lntp 找到占用进程 PID，判断是自己的僵尸进程还是其他服务，再决定 kill 释放端口还是通过 PORT 环境变量换端口。
Tools
相关工具
Latest Updates
最近更新
All Runbooks
全部相关内容
Docker Compose 容器反复重启排查
Docker Compose 容器一直 Restarting 时，用 docker compose ps 看退出码和重启次数，读取失败服务的历史日志、docker compose config 展开环境变量与端口卷，常见根因是启动命令失败、环境变量缺失、端口冲突或 depends_on 未等依赖 ready。
排障Docker 镜像清理与瘦身
Docker 镜像和构建缓存占满磁盘时，用 docker system df 查看整体占用，按 dangling 中间层、未使用镜像、构建缓存的顺序渐进清理，避免直接 docker system prune -a 误删仍被停止容器引用的镜像。
排障Docker 镜像拉取失败排查：超时、证书和架构不匹配
docker pull 出现 TLS handshake timeout、manifest unknown、no matching manifest 或 x509 unknown authority 时，先按错误文本区分网络、Registry 认证、镜像 tag 不存在或 CPU 架构不匹配，再针对性配置代理、镜像源、docker login 或私有仓库 CA。
排障Docker 容器网络不通排查
Docker 容器之间 ping/curl 不通、DNS 无法解析容器名或访问不了宿主机服务时，用 docker network inspect 查看网络成员，确认容器是否在同一自定义 network，Docker 内置 DNS 只在自定义网络生效，宿主机访问用 host.docker.internal。
排障Docker 端口映射后外部访问不了怎么排查
Docker 用 -p 映射端口后从宿主机或外部访问不通时，先确认 docker ps 是否显示 0.0.0.0:host->container 映射，再进容器 ss -lntp 检查应用是否监听 0.0.0.0 而非 127.0.0.1，最后排查 firewalld/ufw/云安全组。
排障Docker Volume 权限拒绝排查
Docker 挂载卷后容器进程写文件报 permission denied 时，用 docker exec id 查看容器运行用户 UID，对比宿主机目录 owner 和 mode，再决定是 chown 目录还是通过 --user、Dockerfile USER 或 SELinux :Z 调整容器用户匹配宿主机权限。
排障Linux 磁盘占满排查与安全清理
Linux 报 No space left on device 或磁盘占满时，用 df -hT 定位具体挂载点，du --max-depth 逐层找大目录，journalctl --disk-usage 和 docker system df 排查日志/镜像占用，lsof +L1 找已删除但仍被进程持有的文件释放空间。
排障Linux OOM Killer 与内存不足排查
Linux 进程被 OOM Killer 杀、容器状态 OOMKilled 或 dmesg 出现 Out of memory: Killed process 时，用 dmesg -T 与 journalctl -k 查历史内核日志确认时间和被杀进程，区分宿主机 OOM 与容器 cgroup 限制，再看进程 RSS 增长趋势排查泄漏。
排障Node.js EADDRINUSE 端口被占用排查
Node.js 启动服务报 Error: listen EADDRINUSE: address already in use :::3000 时，用 lsof -iTCP:3000 -sTCP:LISTEN 或 ss -lntp 找到占用进程 PID，判断是自己的僵尸进程还是其他服务，再决定 kill 释放端口还是通过 PORT 环境变量换端口。
排障PostgreSQL connection refused 排查方法
psql 连接 PostgreSQL 报 could not connect to server: Connection refused 时，先确认服务是否 running、5432 是否监听、postgresql.conf 的 listen_addresses 是否绑定到目标 IP，再逐层排查防火墙、安全组和 Docker 端口映射，pg_hba.conf 只影响后续认证。
排障Spring Boot 端口被占用怎么解决
Spring Boot 启动报 Web server failed to start: Port 8080 was already in use 时，Linux 用 lsof -iTCP:8080 -sTCP:LISTEN、Windows 用 netstat -ano | findstr :8080 找占用进程，判断是自身僵尸 Java 进程还是他人服务，再决定 kill 释放或通过 --server.port 换端口。
命令Docker 查看容器日志与状态命令
使用 docker logs、inspect、stats、events 排查容器启动失败或运行异常的常用命令，docker ps -a 看退出状态，docker logs --tail 200 -f --since 读取近期日志，docker inspect 展开端口、挂载和环境变量，stats 看资源占用。
命令lsof 查看文件句柄和端口命令
lsof 查看文件句柄、端口和网络连接占用的常用命令，lsof -iTCP:8080 -sTCP:LISTEN 找端口监听进程、lsof -p <pid> 查进程打开的所有文件、+D 递归扫描目录、+L1 找已删除但仍被打开的文件，配合 /proc/<pid>/limits 判断 nofile 限制。