你这问题我太熟了。EMQX 是 MQTT 服务器平时很少有人通过它的 HTTP API 去下载超大文件但一旦批量导数据、拉取监控记录、备份配置文件超过几百 MB就会在下载途中被服务器主动掐断然后抛出一句requests.exceptions.ChunkedEncodingError。第一次遇到时我还以为是 EMQX 对大文件下载支持得不好后来在生产环境被这个报错折磨了两轮才搞明白——问题根本不是 EMQX 恋不恋战而是从客户端到反向代理再到 EMQX 监听器这条链路上每一个环节都有它自己的“超时耐心”任何一环先失去耐心TCP 连接就会被主动 reset客户端看到的表象就是 chunked 流中断。这篇内容我围绕这个报错做了完整复盘先拆解ChunkedEncodingError的底层原理再给出一套客户端 requests 的正确写法、EMQX 和 Nginx 侧的关键配置最后把问题排查路径和几个我踩过的坑一次性讲透。适合正在被 EMQX API 下载耗时卡住的同学也适合所有通过 requests 下载大文件时遇到连接中途断掉的人参考。1. 问题现象与根因拆解ChunkedEncodingError 到底在说什么1.1 报错链路请求在每个环节经历了什么很多第一次见ChunkedEncodingError的人会默认把它当成“网络不好”或者“服务器文件有问题”。实际上这个异常的触发条件非常具体HTTP/1.1 协议下服务器响应大文件时不会先算好总长度再一次性返回 Content-Length而是使用分块传输编码把响应体切成一个个数据块依次发送最后一个长度为零的块表示传输结束。HTTP/1.1 200 OK Content-Type: application/octet-stream Transfer-Encoding: chunked 1f4000 200KB 数据 1f4000 200KB 数据 0requests 底层依赖 urllib3 去解析这种分块响应每收到一个 chunk 就按块内声明的字节长度去读。如果响应还没读到结束标志0\r\n\r\nTCP 连接却被对端主动关闭urllib3 就会把这次失败包装成ChunkedEncodingError通常还会附带一段辅助信息requests.exceptions.ChunkedEncodingError: (Connection broken: ConnectionResetError(104, \Connection reset by peer\), ConnectionResetError(104, Connection reset by peer))这里有两个重点需要理解。第一我们并没有等到“整个文件下载时间的超时”才报错而是连接在中途被对方用 RST 或者 FIN 掐掉了客户端读到一半发现数据流没了。第二掐断连接的不一定是 EMQX 本身很可能是某一层代理服务认为这个连接已经“空闲”或“超时”主动清了场。1.2 “超时”不是单一来源而是三层叠加把一次完整的下载请求拉直来看数据从 EMQX 到你的 Python 进程至少要经过三层。每一层都有自己的超时阈值而且默认值通常都非常保守远不够传一个 GB 级文件。客户端这一层最简单直接就是 requests 的 timeout 参数。如果只给一个数字比如timeout30那么“建立连接”和“两次读取之间间隔”都会被限制在 30 秒内。大文件下载过程中只要 TCP 包间隔超过 30 秒客户端就会主动放弃抛ReadTimeoutError。如果恰好是服务器正在忙于生成数据、暂时没有字节发出来客户端还会在这个等待过程中被服务器端的 idle 超时抢先掐断。代理层是重灾区。Nginx 反代 EMQX 时proxy_read_timeout默认只有 60 秒。这里的计时不是“整个下载总时长”而是“每次从上游读取数据包的间隔时间”。60 秒听起来不短但遇到服务器生成大文件比较慢、或者客户端回包速度跟不上时很容易触发。服务器层容易被忽略。EMQX 的 HTTP APIDashboard API、Management API底层是 Erlang 的 cowboy HTTP 服务器监听器带有一个 idle_timeout 参数默认 60 秒左右。这个参数的含义是“连接在多久没有任何读写活动后可以被关闭”。注意它不区分你是在等待文件生成还是真的在下载只要连接空闲超过阈值就会被服务端直接断开。1.3 大文件的特殊之处为什么小文件从来不出问题这个问题只出现在超大文件上不是偶然。几 MB 的小文件从服务器生成到传输完成可能只有几百毫秒不管哪一层的超时都来不及触发。但 GB 级文件就不一样了传输时长按分钟算服务端如果还要在内存里组装完整响应这个准备过程本身就可能超过代理层的等待极限。更糟的是如果 API 实现是把整个文件读进内存再返回大文件还会挤压服务器内存导致响应更慢形成恶性循环。所以遇到这种情况第一反应不应该是一味地把超时参数调大而是先搞清楚整个链路里谁先失去耐心。我把排查方法放在第 4 节先讲客户端怎么改才能稳。2. 客户端修正requests 参数与流式下载的完整姿势2.1 timeout 参数的正确写法元组和单值差别巨大按我实测下来的经验下载大文件时 requests 的 timeout 至少要做两件事连接超时不要给太大因为连不连得上很快就有结果读取间隔超时给足因为大文件的网络传输会有抖动块与块之间的间隔可能远超你的直觉。# 错误示范连接和读取都只有 10 秒 resp requests.get(url, timeout10) # 正确示范连接 10 秒读取间隔 300 秒 resp requests.get(url, timeout(10, 300))另一个容易忽略的点是timeout(10, 300)里的第二个值不是“总下载时间上限”而是“相邻两次读取的间隔上限”。文件即使要下载 10 分钟只要每次读数据的间隔小于 300 秒就不会触发客户端的读取超时。这个区别非常关键否则你可能会把 timeout 拉得异常大反而失去了超时保护的意义。2.2 streamTrue 与 iter_content流式写盘的完整代码下载大文件绝对不能直接resp.content或者resp.json()那会把整个文件加载进内存几百 MB 的文件能把进程内存顶到数百 MBGB 级文件直接 OOM。正确姿势是用streamTrue配合iter_content分块写盘。import requests def download_emqx_file(url, save_path, token, chunk_size1024 * 1024): headers {Authorization: fBearer {token}} session requests.Session() session.headers.update(headers) with session.get(url, streamTrue, timeout(15, 300)) as resp: resp.raise_for_status() with open(save_path, wb) as f: for chunk in resp.iter_content(chunk_sizechunk_size): if chunk: f.write(chunk)这里有几个经验细节值得单独说。chunk_size我建议用 1MB 而不是默认的 128 字节因为每次f.write都有系统调用开销块越大写的次数越少下载速度会明显提升1MB 对内存的占用又完全可控。判断if chunk:是有必要的iter_content在某些情况下可能会产生空字节串直接write会多一次无效 IO。用with session.get(...)而不是resp session.get(...)保证不管下载成功还是抛异常连接都能被正确释放。如果你想看到下载进度可以顺带记录已写入的字节数在循环内定期打印百分比。如果响应头里带Content-Length还可以先拿到总大小做校验。不过注意Transfer-Encoding: chunked的响应通常没有 Content-Length需要从其他地方获取文件大小或者依赖服务端提供的元数据接口。2.3 重试与续传处理“下载到一半失败”的工程化方案网络传输不可能永远一次成功尤其文件大、链路长的时候。但这里有个坑对于流式响应urllib3 的重试机制不会自动生效因为请求已经被消费掉了重放一个已经读了半截的响应是不安全的。所以要么自己写上层重试要么支持断点续传。断点续传依赖 HTTP Range 头即客户端告诉服务器“我已有文件前 N 个字节请从 N 开始继续发”。实现思路如下import os def download_with_resume(url, save_path, token, chunk_size1024 * 1024): session requests.Session() session.headers.update({Authorization: fBearer {token}}) offset os.path.getsize(save_path) if os.path.exists(save_path) else 0 headers {Range: fbytes{offset}-} if offset else {} with session.get(url, streamTrue, headersheaders, timeout(15, 300)) as resp: if resp.status_code 206: mode ab elif resp.status_code 200: mode wb offset 0 else: resp.raise_for_status() return total offset with open(save_path, mode) as f: for chunk in resp.iter_content(chunk_sizechunk_size): if chunk: f.write(chunk) total len(chunk)注意如果服务端不支持 Range并且你已经存在了半截文件返回 200 时要把文件重置为从头开始写否则文件会错位。判断206和200就是为了区分这两种情况。还有一个细节EMQX 的 API 不一定支持 Range所以在写续传之前最好先确认服务端是否支持分段请求。如果明确不支持更稳妥的方案是每次失败后删除临时文件、整体重来同时把重试逻辑放在任务外层而不是放在下载循环里。提示下载大文件时一定要写临时文件下载完成后再用os.replace()原子替换为目标文件。否则下载中途崩溃残留的半截文件很容易被后续流程误读这个坑在定时任务脚本里尤其致命。3. 服务端调优EMQX、Nginx 与下载架构的取舍3.1 EMQX 侧的超时参数cowboy 的 idle_timeoutEMQX 的 HTTP API 服务基于 cowboy 构建官方文档里把相关参数挂在监听器配置下。不同版本配置路径有差异EMQX 4.x 通常是dashboard.listener.http.idle_timeoutEMQX 5.x 则放在dashboard.listeners.http.idle_timeout。实际修改时先emqx ctl conf show看一下当前生效值再决定怎么改。# EMQX 5.x emqx.conf 示例 dashboard { listeners.http { bind 0.0.0.0:18083 idle_timeout 600s } }必须澄清一个容易误解的点idle_timeout管的是“连接空闲时间”不是“连接总时长”。也就是说如果大文件一直在传输每个 chunk 之间的间隔很小这个超时不会触发。真正会触发的是客户端发起了下载请求服务端需要花很长时间查询数据库或者生成导出文件这段时间内连接上没有任何 TCP 数据交换服务端就认为连接空闲主动断开。所以 EMQX 侧有两个解决方向一个是在配置里把 idle_timeout 调大适合低频内部工具另一个是根本不要让 HTTP API 同步去生成大文件改成异步任务这个我在 3.3 里展开。另外如果你的 EMQX 版本老cowboy 底层还涉及request_timeout、inactivity_timeout等参数遇到对应报错时一并检查不要只盯一个名字。3.2 Nginx 反代的三个默认值和调整方案多数生产环境不会让客户端直接访问 EMQX 的 18083 端口前面都挡着 Nginx 做 HTTPS 终结和负载均衡。Nginx 作为反向代理时和超时相关的默认值非常害人proxy_connect_timeout60 秒proxy_send_timeout60 秒proxy_read_timeout60 秒。大文件下载最容易撞上的是proxy_read_timeout它表示 Nginx 等待上游响应数据的间隔上限超过就报upstream timed out并主动断开连接。location /api/ { proxy_pass http://emqx_nodes; proxy_http_version 1.1; proxy_set_header Connection ; proxy_set_header Host $host; proxy_set_header Authorization $http_authorization; proxy_buffering off; proxy_read_timeout 600s; proxy_send_timeout 600s; proxy_buffers 8 16k; proxy_buffer_size 16k; }上面这段配置里有三个关键点。第一proxy_read_timeout和proxy_send_timeout统一调到 600 秒给大文件留足余量。第二proxy_buffering off很重要它让 Nginx 边收上游数据边转发给客户端而不是先把整个响应攒到缓冲区再发对于大文件buffering 开启反而容易因为缓冲区耗尽而写出临时文件增加磁盘 IO 延迟。第三proxy_http_version 1.1; proxy_set_header Connection ;是 keepalive 到上游的标准搭配否则 Nginx 到 EMQX 的连接会频繁重建下载连接中途容易出二次断链。如果前面还挂了云负载均衡、CDN 或者云防火墙也要把这些中间设备的空闲会话超时一并核实。很多云 LB 的 idle timeout 只给 60 秒到 300 秒一样会掐大文件的下载连接。一个能有效对抗这些中间层 idle 断连的手段是让客户端 TCP socket 开启 keepalive每隔 30 到 60 秒发一次探测包让中间设备认为连接还活着。requests 层面可以通过自定义 Transport Adapter 实现代码见后面第 4.3 节的踩坑记录。需要注意TCP_KEEPIDLE这类 socket 选项在 Linux 和 Windows 下名称不同跨平台使用时要 try except 降级。import socket import requests from urllib3.connection import HTTPConnection class KeepAliveHTTPConnection(HTTPConnection): def _new_conn(self): conn super()._new_conn() conn.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1) conn.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE, 30) conn.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 15) conn.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 4) return conn class KeepAliveAdapter(requests.adapters.HTTPAdapter): def __init__(self, *a, **kw): super().__init__(*a, **kw) self.poolmanager.pool_classes_by_scheme { http: KeepAliveHTTPConnection, } session requests.Session() session.mount(http://, KeepAliveAdapter())3.3 架构级方案异步导出 轮询下载链接讲完调参我必须认真说一句如果文件已经大到需要 600 秒超时才能传完那继续死磕同步 HTTP API 就是在给未来埋雷。更靠谱的架构是异步导出任务把“生成文件”和“下载文件”完全拆成两段。客户端先发起一个导出请求服务端立刻返回一个任务 ID后台生成文件的动作放到队列里异步执行。客户端每隔几秒轮询任务状态文件生成好之后服务端返回一个预签名的下载地址下载走独立的文件服务或者对象存储。这样做有几个好处单个 HTTP 请求的处理时间被压缩到毫秒级永远不会触发网关的读超时文件服务本身支持 Range、断点续传、CDN 加速生成文件失败可以独立重试不会影响客户端大文件传输的稳定性。EMQX 场景下尤其适合这种方式。比如你要导出一大批设备在线记录或者消息数据与其通过 API 一次性同步拉取不如让服务端把数据落盘推到对象存储里客户端直接拿下载 URL。如果你的数据只是用于分析统计甚至可以走 EMQX 的数据桥接把数据直接转发到数据库或者 S3完全绕开文件下载这个环节。这才是真正不会超时的方案。4. 工程化排查复现、定位与问题速查表4.1 三步定位法先直连、再绕代理、最后看客户端一旦出现ChunkedEncodingError不要急着改代码先用排除法找到断链发生在哪一跳。第一步直连 EMQX 节点测试。绕过 Nginx 和所有中间层用 curl 直接请求 EMQX 的 API 端口下载同一个大文件。curl 默认没有读取超时只要文件存在、服务端没有主动断就能一直等到下载完成。如果直连正常说明服务端没问题问题大概率在 Nginx 或云负载均衡如果直连也断重点看 EMQX 的 idle_timeout 和文件生成逻辑。第二步恢复 Nginx 代理但把proxy_read_timeout调到很大再次测试。这里最好做控制变量直连正常加 Nginx 就断几乎可以锁定 Nginx把超时调大后正常说明就是超时配置问题。看日志时注意 Nginx 的 error.log 里有没有upstream timed out (110: Connection timed out) while reading response header from upstream有就是实锤。第三步回到客户端确认 requests 配置。常见的问题是 timeout 只给了一个较小数字、没有用 stream、chunk_size 太小。这三个因素叠加起来即使服务端正常客户端也会自己把自己逼到超时。4.2 常见问题速查表症状可能原因快速处理小文件正常大文件固定到某个时间点断Nginxproxy_read_timeout或云 LB idle timeout 到点调大 timeoutproxy_buffering off客户端 TCP keepalive下载前等待很久然后被断开服务端生成文件耗时太长连接空闲触发 EMQX idle_timeout调大idle_timeout或改异步导出任务客户端报ReadTimeoutError而非 ChunkedEncodingErrorrequests timeout 设置不合理或者网络有拥塞改为timeout(10, 300)元组形式局域网直连正常跨公网下载必断运营商 NAT 会话超时、防火墙 idle 超时客户端开 TCP keepalive或换文件服务加 CDN进程内存暴涨后报错没有streamTrue整个文件被加载进内存改用iter_content流式写盘下载一半断线后重跑文件错乱没处理续传或残留半截文件写临时文件支持 Range 重试完成后再os.replace4.3 我踩过的坑三次真实排障记录第一次踩坑是在 Nginx 层。现象是单节点直连 EMQX 下载 1GB 文件完全正常一加 Nginx 就稳定在 60 秒左右断。当时我还以为是 Nginx 和 EMQX 之间的 keepalive 有问题后来查日志才发现是proxy_read_timeout默认 60 秒导致的。那个文件需要服务端先花 50 多秒生成第一字节还没发出来Nginx 已经等不及了。把proxy_read_timeout调到 600 秒后问题消失。第二次踩坑是在 EMQX 的 cowboy idle_timeout。下载任务不是普通的静态文件而是实时导出的数据导出的准备时间非常长。在准备期间连接上没有数据流动EMQX 主动把连接关了。我最初尝试调大 idle_timeout确实能解燃眉之急但后来发现只要导出量再大一点还是会卡。最后改成异步任务才彻底解决。第三次是客户端自己的问题。有段时间我在内网测试怎么都不复现部署到生产环境就报错。排查后发现是生产环境那台机器 Python 进程走了 HTTP 代理代理环境的超时策略和本地完全不一样导致下载到一半被掐。requests 默认会读取HTTP_PROXY环境变量内网调试时没这个变量生产环境配了全局代理一下子就把流量全部劫走了。处理办法是给 requests 显式指定proxies{http: None, https: None}或者确认代理配置符合预期。这个问题用 tcpdump 一看就懂数据确实没有从预期网卡出去。5. 额外的两个细节与收尾建议关于这类问题我最后再补两个容易被忽略的细节。一个是下载完成后一定要做完整性校验尤其当文件是导出数据时。不要只看os.path.getsize是否匹配因为如果服务端返回的是 chunked 编码响应头里本来就没有 Content-Length你拿到的大小只能当作参考。正确的做法是服务端额外提供一个文件 MD5 或者 SHA256下载完成后本地算一份哈希做对比。没有哈希的话至少对比文件大小再决定是否继续后续处理。另一个细节是日志和监控。大文件下载的失败经常是偶发的没有日志很难排查。客户端侧把每次下载的开始时间、结束时间、耗时、字节数、错误类型都打出来写入独立的下载日志。服务端侧确认 EMQX 的 access log 和 Nginx 的 error.log 都开到了合适的级别。这样下次再出现断开你翻日志能直接看到是哪一跳先动手而不是像我们当初一样靠猜。我个人在实际操作中的体会是这类问题绝大多数不是“EMQX 不能下载大文件”而是整条下载链路上的某个默认超时设得太短。按我说的三步定位法逐层排查通常半小时内就能锁到具体位置。改配置的时候留个心眼所有超时参数都别只改一层客户端、代理、服务端三处配套调效果才稳定。如果文件量级已经超过 GB 级别我强烈建议一步到位改成异步导出加文件下载链接的模式那才是经得起生产环境考验的长久之计。