Docker构建ADD大文件频繁报‘unexpected EOF’错误，求排查方案

在自托管GitLab集群（配备多台高性能Runner服务器）的CI任务中，执行Docker ADD命令下载14GB大型二进制文件时，多数情况下会失败并抛出以下错误：

Step 5/5 : ADD https://whatver/file.foo
Downloading [==============>            ]  7.919GB/13.86GB
ADD failed: unexpected EOF

仅偶尔能正常完成下载：

Step 5/5 : ADD https://whatver/file.foo
Downloading [==========================>]  13.86GB/13.86GB

已知条件：所有CI服务器空闲磁盘空间充足（>200GB），可在机器上手动复现该问题；已排除特定Docker版本处理TAR文件自动解压的Bug（本次为二进制文件）；排查Docker构建缓存垃圾回收的defaultKeepStorage和keepStorage设置，确认与该问题无关。

• 网络传输不稳定：大文件下载过程中，链路丢包、源服务器临时中断或网络波动，导致下载中途截断，触发unexpected EOF错误。手动可复现说明问题并非CI环境独有，大概率存在网络层面的不稳定因素。
• Docker ADD命令默认超时限制：Docker的ADD命令处理远程文件下载时，存在默认超时阈值，超大文件下载耗时超过该值会被强制中断，进而出现文件不完整的报错。
• 文件系统写入缓存异常：尽管磁盘空间充足，但文件系统的写入缓存策略可能导致下载的文件未及时落盘，或缓存刷新过程中出现异常，被Docker判定为文件损坏。
• Docker版本潜在Bug：部分Docker版本在处理超大文件的ADD操作时，可能存在内存管理或文件流处理的缺陷，导致下载过程中意外截断文件。

• 替换ADD命令为带重试的下载工具：
  放弃直接使用ADD远程文件的方式，改用wget或curl在CI脚本中先下载文件，利用工具的重试机制提升可靠性，示例：

  # 用curl带重试下载文件
  curl -L --retry 5 --retry-delay 3 -o /tmp/file.foo https://whatver/file.foo
  # 用COPY复制到镜像
  COPY /tmp/file.foo /target/path/
  

  同时可添加文件校验步骤，比如提前获取文件的SHA256哈希，下载后执行校验：

  echo "expected_hash  /tmp/file.foo" | sha256sum -c -
  

• 调整Docker daemon下载超时配置：
  修改Docker daemon配置文件（通常为/etc/docker/daemon.json），添加或调整下载超时参数（不同Docker版本参数可能有差异，需对应版本调整），示例：

  {
    "download-timeout": 3600,
    "max-concurrent-downloads": 1
  }
  

  修改后重启Docker daemon生效。
• 排查网络链路稳定性：
  在Runner服务器上使用mtr、ping等工具测试到文件源服务器的链路，排查是否存在持续丢包或高延迟情况；必要时更换文件源为就近镜像，或在集群内部搭建文件缓存节点。
• 验证文件系统与调整缓存策略：
  临时清理系统缓存后测试：

  echo 3 > /proc/sys/vm/drop_caches
  

  若问题消失，可调整文件系统的缓存策略，或在CI任务下载前添加清理缓存的步骤。
• 升级/降级Docker版本：
  查阅Docker官方Release Notes，确认当前版本是否存在超大文件处理相关的Bug，尝试升级至最新稳定版，或降级到已知无此问题的版本。

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