docker Troubleshooting
Docker 容器网络不通排查
Docker 容器之间 ping/curl 不通、DNS 无法解析容器名或访问不了宿主机服务时，用 docker network inspect 查看网络成员，确认容器是否在同一自定义 network，Docker 内置 DNS 只在自定义网络生效，宿主机访问用 host.docker.internal。
先确认容器是否在同一 network，再用 docker exec 进容器 ping/curl 测试，最后检查 DNS 解析和端口监听。
Scenario
这篇文章解决什么问题
适用于“Docker 容器网络不通排查”对应的线上或本地排障场景。不要只根据最终报错下结论，应先把问题拆成入口、链路、目标服务和资源限制几层，再用命令逐层证实。先确认容器是否在同一 network，再用 docker exec 进容器 ping/curl 测试，最后检查 DNS 解析和端口监听。
Symptoms
典型现象
- Docker 容器之间 ping/curl 不通、DNS 无法解析容器名或访问不了宿主机服务时，用 docker network inspect 查看网络成员，确认容器是否在同一自定义 network，Docker 内置 DNS 只在自定义网络生效，宿主机访问用 host.docker.internal。
- 相关日志、命令或页面中反复出现 docker、network、bridge 等关键词。
- 同一服务在不同机器、不同入口或不同时间段表现不一致，需要通过证据链缩小范围。
Before Debugging
排查前先确认
- 先确认问题发生在镜像拉取、容器启动、容器内服务监听，还是宿主机/外部访问。
- 记录 docker ps、docker logs 和 docker inspect 的同一时间窗口，避免状态已变化后误判。
- 区分 Docker 网络、宿主机防火墙、云安全组和应用自身监听地址。
Root Causes
常见根因分层
容器状态和应用状态不是一回事
容器 Running 只代表主进程存在，不代表应用已经 ready；容器 Restarting 通常是应用启动失败或健康检查不断失败。
- 看退出码和最近 200 行日志
- 检查 healthcheck 是否过于激进
- 确认依赖服务是否 ready
端口、网络和监听地址不匹配
服务只监听 127.0.0.1、端口映射写错、bridge 网络不可达、宿主机防火墙拦截，都会造成“容器里通、外部不通”。
- 容器内 ss -lntp
- 宿主机 curl 127.0.0.1:端口
- 外部机器再测宿主机 IP
Registry、代理和平台架构问题
镜像拉取失败不仅是网络慢，也可能是认证、标签不存在、私有 CA、代理环境变量或 amd64/arm64 架构不匹配。
- 保留完整 pull 错误
- 检查 docker info 中代理配置
- 用 manifest inspect 看架构
Diagnosis Path
分步诊断流程
1. 固定现场，避免追着变化状态跑
先记录故障时间、影响入口、完整错误和最近一次变更。Docker 容器网络不通排查 这类问题经常在重启、重试或缓存刷新后短暂消失，没有现场信息会很难复盘。
- 截图或保存完整错误文本
- 记录请求域名/IP/端口/namespace/服务名
- 标出最近发布、配置、证书、镜像或依赖变更
docker network ls
docker network inspect <network>2. 在故障发生的同一位置复现
很多误判来自测试位置不同：本机通不代表服务器通，容器内通不代表宿主机通，集群外通也不代表 Pod 内通。复现命令要尽量贴近真实流量路径。
- 从报错服务所在机器执行测试
- 必要时加 Host、SNI、namespace 或代理参数
- 把成功路径和失败路径的输出并排比较
docker network inspect <network>
docker exec -it <container> ping <other-container>
docker exec -it <container> nslookup <service>3. 读取服务端证据，而不是只看客户端提示
客户端报错通常是结果摘要。真正能区分根因的是服务端日志、内核日志、事件、进程状态或数据库状态。
- 确认两个容器是否在同一 Docker network。
- 用 docker network inspect 查看网络成员和 IP 分配。
- 进入容器用 ping/curl 测试容器间连通性。
docker exec -it <container> ping <other-container>
docker exec -it <container> nslookup <service>
docker run --rm --network <network> busybox sh -c "curl -v http://<service>:8080"4. 做最小修复并立即回归验证
每次只改一个变量，修复后用同一条复现命令回测，并观察日志是否停止增长。这样可以避免多个临时改动互相掩盖。
- 进入容器用 ping/curl 测试容器间连通性。
- 检查容器内 DNS 解析是否正常，Docker 内置 DNS 只在自定义网络生效。
- 容器访问宿主机服务用 host.docker.internal 或宿主机 IP。
docker exec -it <container> nslookup <service>
docker run --rm --network <network> busybox sh -c "curl -v http://<service>:8080"Commands
排查命令与使用意图
命令 1
用于补充“Docker 容器网络不通排查”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
docker network ls命令 2
用于补充“Docker 容器网络不通排查”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
docker network inspect <network>命令 3
用于验证网络连通性。ping 测试 ICMP 层，telnet/nc 测试 TCP 层连通，排除防火墙和安全组拦截。
docker exec -it <container> ping <other-container>命令 4
用于补充“Docker 容器网络不通排查”的排查证据链。docker 的输出需要结合上下文其他命令交叉验证，不要单独依赖某一条结果下结论。
docker exec -it <container> nslookup <service>命令 5
用于从指定位置模拟真实请求。加 -v 可以看到 DNS、TCP、TLS、HTTP 头和代理连接过程，是定位链路阶段的关键证据。
docker run --rm --network <network> busybox sh -c "curl -v http://<service>:8080"Risk Notes
容易踩坑的地方
- 不要一上来 docker system prune，先确认是否有需要保留的停止容器、卷或构建缓存。
- 不要把 restart: always 当成稳定性方案，它可能掩盖启动失败的根本原因。
- 不要在容器内使用 systemd 作为入口进程，除非使用特权模式或专门的基础镜像。
Verification
修复后怎么确认
- 原始故障现象已经消失，且使用同一入口重新测试 Docker 容器网络不通 能稳定成功。
- 服务端日志不再出现同类错误，监控中的错误率、重启次数、连接数或延迟回到正常区间。
- 如果做过临时绕过，已经记录恢复计划，例如还原宽松策略、补监控、补限制或提交正式配置。
Prevention
后续预防
- Compose 文件里显式写健康检查、资源限制和必要环境变量，确保容器启动后能自动恢复。
- 上线前用 docker compose config 展开最终配置做审查，避免遗漏或覆盖了错误的配置值。
- 为镜像使用固定 tag 或 digest，避免 latest 漂移导致部署了非预期的版本。
- 建立容器日志轮转策略，防止日志无限增长撑满磁盘分区。
常见问题
容器间能用容器名互相访问吗？
在同一自定义 Docker network 中可以，Docker 内置 DNS 会解析容器名。默认 bridge 网络不支持容器名解析。
host.docker.internal 是什么？
它指向宿主机 IP，容器内可用它访问宿主机上的服务。Linux 上需要加 --add-host=host.docker.internal:host-gateway。
Long-tail SEO
你可能正在搜索这些报错
下面这些错误原文、场景词和中英文搜索词，都是排查同类问题时常见的入口。
- docker 容器网络不通
- docker network bridge 通信
- docker 容器间 ping 不通
- docker DNS 解析失败
- docker network inspect
- docker 自定义网络 容器名解析
- docker host.docker.internal
- docker compose 网络隔离
Need More Help
这个问题还没完全解决？
把你的报错、环境和已经尝试过的步骤发给我，后续会优先补充到排障手册。