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 配置仅需确保这些请求毫秒级透传、不超时、不截断——它只是管道，不是大脑

不复杂但容易忽略