本文详解 docker-compose up 因 HTTP 连接超时（UnixHTTPConnectionPool Read timed out）导致失败的原因，提供重启 Docker 服务、延长超时时间等实用解决方法，并适配 CI/CD 环境（如 Jenkins agent）中的高负载场景。
本文详解 `docker-compose up` 因 http 连接超时（unixhttpconnectionpool read timed out）导致失败的原因，提供重启 docker 服务、延长超时时间等实用解决方法，并适配 ci/cd 环境（如 jenkins agent）中的高负载场景。
在使用 docker-compose up 启动包含大量服务（例如 14 个容器）的复杂测试环境时，Jenkins agent 上偶发出现如下错误：
ERROR: for testdb-data UnixHTTPConnectionPool(host='localhost', port=None): Read timed out. (read timeout=60) An HTTP request took too long to complete. Retry with --verbose to obtain debug information. If you encounter this issue regularly because of slow network conditions, consider setting COMPOSE_HTTP_TIMEOUT to a higher value (current value: 60).
该报错本质并非网络连接失败，而是 Docker 客户端（通过 Unix socket 与 dockerd 通信）在默认 60 秒内未能收到某个容器操作（如创建 volume testdb-data）的响应，触发了 requests 库的读取超时机制。
根本原因通常与以下因素相关：
-
Docker daemon 响应延迟：高负载下（CPU/IO 密集型构建任务并行运行），
dockerd处理请求队列积压，尤其在创建多个卷、拉取镜像或初始化网络时； -
旧版工具链限制：您使用的
docker 1.10.1和docker-compose 1.13.1属于较早期版本（2016 年发布），其默认超时策略和资源调度机制对大规模编排支持较弱； -
守护进程状态异常：长时间运行后，
dockerd可能因内存碎片、goroutine 泄漏或 socket 文件句柄耗尽而响应迟缓。
✅ 推荐解决方案（按优先级排序）：
1. 临时恢复：重启 Docker 服务
立即释放资源、清理内部状态：
sudo systemctl restart docker
⚠️ 注意：此操作会终止当前所有运行中的容器，请确保在 CI agent 上无关键长期服务依赖。
2. 持久化修复：延长超时阈值
在 Jenkins agent 的执行环境（如 Jenkinsfile 或 agent 启动脚本）中设置环境变量：
export DOCKER_CLIENT_TIMEOUT=120 export COMPOSE_HTTP_TIMEOUT=120
这两项分别控制：
-
DOCKER_CLIENT_TIMEOUT：Docker CLI 与 daemon 通信的整体超时（单位：秒）； -
COMPOSE_HTTP_TIMEOUT：docker-compose 内部 HTTP 请求（如容器启动、健康检查等待）的超时（单位：秒）。
建议将二者设为相同值（如 120），避免组合调用中某一层先超时。若仍偶发失败，可进一步提升至 180，但需同步排查底层资源瓶颈。
3. 长期优化建议
- ✅ 升级 Docker 和 Compose：升级至 Docker Engine ≥ 20.10 + docker-compose v2（即
docker composeCLI 插件），新版显著优化并发性能与错误恢复能力； - ✅ 资源隔离：为 Jenkins agent 设置 CPU/memory 限制（如
--cpus=4 --memory=8g），避免单次测试抢占全部资源； - ✅ 分阶段启动：使用
docker-compose up -d service-a service-b分批启动非强依赖服务，降低单次请求负载； - ✅ 日志诊断：添加
--verbose参数捕获详细堆栈，结合journalctl -u docker -n 100 --no-pager查看 daemon 级延迟线索。
? 提示：该问题在 GitHub 上已被多次报告（issue #3927、#4486、#3834），社区共识是“超时值不足”为主因，而非必须修复的 bug——合理调优比强行降级更可靠。
通过以上组合策略，可稳定支撑 Jenkins 中高频、多容器的集成测试场景，显著降低 UnixHTTPConnectionPool 超时中断率。
