macOS下Docker容器内curl -o传文件时curl: (56)错误解决

问题重现 #

在macOS环境下，Docker容器内执行curl拉取主机Python HTTP服务器上的大文件时，频繁出现传输中断，错误提示：

curl: (56) Recv failure: Connection reset by peer

操作步骤 #

1. 主机启动Python内置HTTP服务器：

   nohup python3 -m http.server > python_server.log &
   

2. Docker容器内执行下载命令：

   curl -o /tmp/guan-data-1.0-SNAPSHOT.zip http://docker.for.mac.localhost:8000/guan-data-1.0-SNAPSHOT.zip
   

服务器日志异常 #

主机Python服务器日志出现BrokenPipeError，说明传输过程中连接被意外断开：

::ffff:127.0.0.1 - - [07/Jun/2023 15:06:28] "GET /guan-data-1.0-SNAPSHOT.zip HTTP/1.1" 200 -
----------------------------------------
Exception occurred during processing of request from ('::ffff:127.0.0.1', 59020, 0, 0)
Traceback (most recent call last):
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/socketserver.py", line 683, in process_request_thread
 self.finish_request(request, client_address)
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/socketserver.py", line 360, in finish_request
 self.RequestHandlerClass(request, client_address, self)
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/http/server.py", line 653, in __init__
 super().__init__(*args, **kwargs)
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/socketserver.py", line 747, in __init__
 self.handle()
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/http/server.py", line 427, in handle
 self.handle_one_request()
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/http/server.py", line 415, in handle_one_request
 method()
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/http/server.py", line 660, in do_GET
 self.copyfile(f, self.wfile)
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/http/server.py", line 860, in copyfile
 shutil.copyfileobj(source, outputfile)
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/shutil.py", line 208, in copyfileobj
 fdst_write(buf)
File "/opt/homebrew/Cellar/python@3.9/3.9.7_1/Frameworks/Python.framework/Versions/3.9/lib/python3.9/socketserver.py", line 826, in write
 self._sock.sendall(b)
BrokenPipeError: [Errno 32] Broken pipe
----------------------------------------

注：直接在主机使用curl拉取文件无异常，问题仅出现在Docker容器内。

排查分析 #

1. Python内置HTTP服务器局限性：python3 -m http.server是单线程同步实现，没有针对大文件传输做优化，也缺乏连接超时、缓冲调整等机制，长时间传输时容易因网络波动或资源不足导致连接断开。
2. Docker for Mac网络转发特性：docker.for.mac.localhost是Docker for Mac提供的主机别名，其网络转发路径比直接localhost更复杂，大文件传输时可能出现超时或丢包。
3. 容器/主机资源限制：Docker分配的内存、CPU不足，或主机系统TCP参数设置不合理，导致连接无法维持长时间传输。

解决与排查方案 #

1. 替换稳定的HTTP服务器 #

放弃Python内置server，改用异步或生产级HTTP服务器：

• 使用aiohttp异步服务器（需先安装pip install aiohttp）：

  nohup python3 -m aiohttp.web -H 0.0.0.0 -P 8000 > aio_server.log &
  

• 或使用nginx：在主机部署nginx，将文件目录配置为静态资源路径，稳定性更强。

2. 调整curl参数增强容错 #

给curl添加重试、超时和保活参数，提升传输稳定性：

curl -o /tmp/guan-data-1.0-SNAPSHOT.zip \
  --retry 3 \
  --retry-delay 2 \
  --connect-timeout 60 \
  --keepalive-time 60 \
  http://docker.for.mac.localhost:8000/guan-data-1.0-SNAPSHOT.zip

• --retry：传输失败后重试次数
• --keepalive-time：保持TCP连接的间隔时间
• --connect-timeout：设置连接超时时间

3. 优化Docker网络配置 #

• 改用主机实际IP代替docker.for.mac.localhost：查看主机局域网IP（如ifconfig | grep inet），容器内直接访问http://192.168.x.x:8000/...，绕过Docker的localhost转发层。
• 检查Docker资源分配：打开Docker Desktop设置，增加内存（建议至少4GB）和CPU配额，避免资源不足导致连接中断。

4. 调整系统TCP参数 #

在macOS终端执行以下命令，调整TCP保活参数，减少连接被主动断开的概率：

sudo sysctl -w net.inet.tcp.keepidle=300000
sudo sysctl -w net.inet.tcp.keepintvl=60000
sudo sysctl -w net.inet.tcp.keepinit=60000

• keepidle：连接空闲多久后开始发送保活包
• keepintvl：保活包发送间隔
• keepinit：初始连接超时时间

内容的提问来源于stack exchange，提问作者Hex.J