MacOS Big Sur配置端口映射后无法访问Docker容器网页问题排查

可能的原因 #

• 服务未完成初始化：docker ps仅展示容器进程的运行状态，Spring Cloud微服务和Zipkin这类Java应用在容器启动后，还需要拉取配置、完成服务注册、端口绑定等步骤才会对外提供服务，512M的内存限制也会拉长启动耗时，容易出现容器状态为Up但服务实际未就绪的情况。
• Docker Desktop端口转发异常：你使用的是较老版本的Mac版Docker Desktop，该版本存在已知的宿主机到Linux虚拟机的端口转发失效bug，会出现端口映射配置正常但宿主机无法访问的问题。
• 网络协议优先级问题：Mac默认会优先使用IPv6访问localhost，而Docker默认的端口映射仅绑定IPv4的0.0.0.0地址，会导致请求走到IPv6时被拒绝。
• 容器内服务绑定地址错误：如果服务启动时仅绑定容器内的127.0.0.1地址，就算端口映射配置正常，外部也无法访问到服务。

排查步骤 #

1. 验证容器内服务可用性
   进入对应容器内部测试端口是否正常监听、服务是否可用：

# 测试Zipkin服务
docker exec -it tracing-server curl http://127.0.0.1:9411
# 测试API网关服务
docker exec -it api-gateway curl http://127.0.0.1:8080

如果容器内部访问也失败，说明是服务本身启动异常，和端口映射无关。
2. 查看服务启动日志
检查服务是否有报错：

docker logs api-gateway
docker logs tracing-server

重点查看是否有配置拉取失败、服务注册失败、端口绑定冲突的异常日志。
3. 验证宿主机端口占用
检查本地是否有其他进程占用对应端口：

sudo lsof -i :8080
sudo lsof -i :9411

4. 测试IPv4直连
   直接用IPv4地址访问，排除IPv6优先级影响：

curl http://127.0.0.1:8080
curl http://127.0.0.1:9411

解决方案 #

• 服务未就绪：等待3-5分钟后再次尝试访问，集群规模较大且有内存限制的情况下，全服务启动完成需要较长时间。
• 端口转发异常：先执行docker-compose down && docker-compose up -d重新拉起容器，如果问题依旧可以重启Docker Desktop，或者升级到最新稳定版的Docker Desktop修复已知bug。
• IPv6优先级问题：可以在docker-compose的端口映射配置中显式指定绑定IPv4地址，示例：

  ports:
   - "127.0.0.1:8080:8080"
   - "127.0.0.1:9411:9411"
  

• 服务绑定地址错误：修改服务启动参数，Spring Boot服务增加--server.address=0.0.0.0启动参数，Zipkin配置SERVER_ADDRESS=0.0.0.0环境变量，确保服务监听容器内所有网卡地址。

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