本文详解 docker-compose up 报错 UnixHTTPConnectionPool Read timed out 的根本原因及实用解决方法，包括环境变量调优、Docker 服务重启和资源监控建议。
本文详解 `docker-compose up` 报错 `unixhttpconnectionpool read timed out` 的根本原因及实用解决方法，包括环境变量调优、docker 服务重启和资源监控建议。
在 CI/CD 环境（如 Jenkins Agent）中批量启动多服务 Docker Compose 栈时，常遇到如下超时错误：
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 Compose 客户端与 Docker Daemon 通信过程中，等待响应时间超过默认阈值（60 秒） 所致。尤其在高负载场景下（如 Jenkins Agent 同时运行 20+ 测试、启动约 14 个容器），Docker Daemon 可能因资源争用（CPU、I/O、内存压力）或镜像拉取/容器初始化延迟，导致单个 API 调用（例如创建 volume、检查网络、启动依赖容器）耗时突增，最终触发客户端超时。
✅ 推荐解决方案
1. 增加超时阈值（最直接有效）
Docker Compose 使用两个关键环境变量控制超时行为：
-
COMPOSE_HTTP_TIMEOUT：控制 Compose 与 Docker Daemon 通信的 HTTP 请求最大等待时间（单位：秒）； -
DOCKER_CLIENT_TIMEOUT：部分旧版本 Compose（如 1.13.1）同时受此变量影响，建议一并设置。
在 Jenkins Agent 的执行环境（如 Jenkinsfile 或启动脚本）中提前导出：
export COMPOSE_HTTP_TIMEOUT=120 export DOCKER_CLIENT_TIMEOUT=120
⚠️ 注意：变量需在
docker-compose up执行前生效；若使用sudo，注意环境变量是否被重置（推荐用sudo -E保留环境，或在/etc/environment中全局配置）。
2. 重启 Docker 服务（临时恢复）
当 Docker Daemon 内部状态异常（如 goroutine 积压、socket 队列满、存储驱动卡顿）时，单纯调高超时可能治标不治本。可加入前置健康检查与自动恢复逻辑：
# 检查 Docker 是否就绪
timeout 30 sh -c 'until docker info >/dev/null 2>&1; do sleep 2; done' || {
echo "Docker daemon unresponsive — restarting..." >&2
sudo systemctl restart docker
sleep 5
}
# 再次验证
docker info >/dev/null || { echo "Failed to start Docker daemon"; exit 1; }
3. 优化 Compose 启动行为（预防性措施）
- 使用
--no-deps+ 分阶段启动：对非强依赖服务延后启动，降低并发压力； - 添加
--quiet-pull减少日志 I/O 开销； - 在
docker-compose.yml中为启动慢的服务显式设置healthcheck和restart: on-failure，避免阻塞整体流程； - 升级工具链：您当前使用的
docker 1.10.1和docker-compose 1.13.1属于 2016 年发布的老旧版本（已 EOL），存在已知超时处理缺陷（见 issue #3927）。强烈建议升级至 Docker Engine 24.x + Compose V2（docker composeCLI），其超时机制更健壮、并发控制更优。
? 排查建议
- 监控 Agent 资源：通过
top、iostat -x 1、docker system df确认是否存在磁盘空间不足、inode 耗尽或 overlay2 层过多； - 启用调试日志：
docker-compose --verbose up可定位具体卡在哪个 API 调用（如POST /v1.24/volumes/create）； - 检查 Docker 日志：
journalctl -u docker -n 100 --no-pager查看 Daemon 是否出现failed to start daemon:...或graphdriver错误。
综上，超时本质是资源瓶颈下的信号丢失，而非配置错误。优先通过 COMPOSE_HTTP_TIMEOUT=120 快速缓解，同步推进 Docker 升级与资源治理，方为长效之策。
