Nginx 本身不支持断点续传，需通过调优超时与缓冲参数、透传关键请求头和方法、启用连接复用，并由后端实现 TUS 等协议及状态持久化来协同完成中断恢复。
Nginx 使用 proxy_pass 转发大文件上传时，默认配置极易因超时、缓冲区限制或客户端断连导致中断，且原生不支持断点续传（HTTP Range 上传）。要实现“中断恢复”，关键不是让 Nginx 自身接管续传逻辑，而是协同后端服务，确保上传链路稳定、超时合理、请求完整透传，并由后端（如应用服务器）真正处理分块上传或断点续传。以下是具体要点：
调整超时与缓冲参数，避免中间层主动断连
Nginx 在代理大文件上传时，若未调优，会在几秒到几十秒内关闭空闲连接，导致长上传中断。需显式延长以下指令：
-
client_max_body_size：设为足够大（如
0表示不限制，或明确值如4G），否则上传超限直接返回 413 -
client_body_timeout：设置客户端发送请求体的超时时间（如
300s），防止上传慢被中断 -
proxy_connect_timeout、proxy_send_timeout、proxy_read_timeout：分别控制与后端建连、发请求、收响应的超时；大文件上传建议统一设为
600或更高（单位：秒） -
proxy_buffering off：对大文件上传建议关闭缓冲（尤其使用流式上传时），避免 Nginx 缓存整个请求体耗尽内存；同时需配
proxy_request_buffering off（Nginx ≥ 1.13.10）禁用内部重试缓冲，防止 chunked 请求被误读
透传原始请求头与方法，支持分块/断点协议
若后端实现的是基于 Content-Range 的断点续传（如 TUS 协议、自定义 Range 上传），Nginx 必须不篡改关键字段：
CPA Update - Secure CLI Proxy API Maintenance
下载
安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。
- 确保 不修改或丢弃
Content-Range、Upload-Length、Tus-Resumable等自定义头，用proxy_pass_request_headers on（默认开启）并避免proxy_hide_header错误拦截 - 若后端依赖原始 HTTP 方法（如
PATCH续传），确认 Nginx 未强制转为POST；proxy_pass默认透传方法，无需额外配置 - 如需透传真实客户端 IP 供后端校验，用
proxy_set_header X-Real-IP $remote_addr和X-Forwarded-For
启用健康检查与连接复用，提升链路鲁棒性
上传过程长，网络抖动易触发连接重置。可通过以下降低失败率：
- 在
upstream块中启用 keepalive：如keepalive 32复用后端连接，减少握手开销 - 配合
proxy_http_version 1.1和proxy_set_header Connection ''清除 Connection: close，确保 HTTP/1.1 持久连接生效 - 对关键后端加
health_check（需 stream 模块或第三方模块），避免将请求发往已卡死的实例
后端才是续传核心，Nginx 只负责可靠转发
Nginx 本身不解析上传内容、不管理文件分片、不存储临时 offset。所谓“中断恢复”，实际依赖：
- 后端提供标准接口（如 TUS 协议的
POST /files创建上传、PATCH /files/{id}追加数据、HEAD /files/{id}查询进度） - 后端将上传状态（如已写入字节数、临时文件路径）持久化到 Redis 或数据库，供重试时查询
- 前端使用支持断点的 SDK（如
tus-js-client），自动检测上次中断位置并从Content-Range指定偏移续传 - Nginx 配置仅需确保这些请求毫秒级透传、不超时、不截断——它只是管道，不是大脑
不复杂但容易忽略
