CircleCI Docker Executor中docker-compose容器网络互通问题排查

我之前在CircleCI里折腾容器间通信的时候也踩过不少坑，结合你提到的场景，给你几个针对性的排查和解决方向：

1. 改用自定义Docker网络，避免默认bridge的限制 #

CircleCI的Docker executor环境里，默认的bridge网络对容器间访问有不少隐性限制。最稳妥的方式是创建一个专属的自定义网络，把服务端和客户端容器都挂到这个网络上：

# 创建自定义网络
docker network create test-network

# 启动服务端容器时指定该网络
docker run -d --name server --network test-network your-server-image

# 启动客户端容器时使用同一网络
docker run --name client --network test-network your-client-image

这样两个容器就能直接通过容器名称（比如server）互相访问，不用纠结IP地址的问题。

2. 确认服务端监听的是0.0.0.0而非localhost #

很多时候容器间访问失败，是因为服务端的服务只绑定了localhost（127.0.0.1），这时候只有容器内部能访问，外部容器根本连不上。你得确保服务端的服务监听0.0.0.0，比如：

• 如果是HTTP服务，启动命令里加上--bind 0.0.0.0:8080
• 如果是Node.js服务，设置server.listen(8080, '0.0.0.0')

3. 区分远程Docker与主容器的网络环境 #

如果你在配置里用了setup_remote_docker步骤，那所有docker命令都是在远程Docker daemon里执行的，这时候主job容器和远程Docker里的容器网络是隔离的：

• 如果客户端是在主job容器里运行，那需要把服务端容器的端口映射到远程Docker主机，然后通过localhost访问（CircleCI会自动把远程Docker的端口转发到主容器的localhost）：

# 在远程Docker里启动服务端，映射端口到主机
docker run -d --name server -p 8080:8080 your-server-image

# 主容器里的客户端直接访问localhost:8080
curl localhost:8080

4. 添加健康检查，确保服务就绪后再启动客户端 #

经常遇到的情况是：客户端已经发起请求了，但服务端容器里的服务还没完全启动好。给服务端容器加个健康检查，等服务就绪后再跑客户端：

# 启动服务端时配置健康检查
docker run -d --name server \
  --health-cmd "curl -f http://localhost:8080/health || exit 1" \
  --health-interval 5s \
  --health-timeout 3s \
  --health-retries 3 \
  your-server-image

# 等待服务端健康状态变为healthy
until docker inspect --format='{{.State.Health.Status}}' server | grep -q healthy; do
  sleep 1
done

# 再启动客户端容器
docker run --name client your-client-image

你可以对照复现仓库里的具体配置，对应调整这些步骤。比如检查Docker命令里有没有指定自定义网络，服务端的监听地址是否正确，或者是否需要添加健康检查等待服务就绪。

内容的提问来源于stack exchange，提问作者mRcSchwering