nginx实现极速实时数据流分发需关闭proxy_buffering off并精细化配置：仅在/events、/stream等路径启用，同步禁用gzip、proxy_cache，设置proxy_http_version 1.1、connection空头、proxy_read_timeout 300，并开启tcp_nodelay、保留proxy_buffer_size 4k。

要让 Nginx 实现极速实时数据流分发、跳过网关层中间缓冲，核心不是“关一个开关”，而是把 proxy_buffering off 作为起点，配合协议、超时、压缩和底层传输行为一并调整。它本质是把 Nginx 从“缓存中转站”变成“低延迟管道”，适用于 SSE、LLM token 流、实时日志、HMR 热更新等对首字节时间（TTFB）和帧间隔敏感的场景。

必须关闭 proxy_buffering 的典型路径

不要在 http 或 server 块全局关闭——这会破坏其他 API 的稳定性。应按业务路径精细化控制：

• /events、/stream、/llm/chat：SSE 或 LLM 流式响应入口，显式加 proxy_buffering off;
• /__webpack_hmr 或 /hot：前端开发服务器热更新接口，同样需关闭缓冲
• /api/upload/chunk：若后端支持流式接收分片，也建议同步关闭（再搭配 proxy_request_buffering off）

关闭后必须同步禁用的配套项

proxy_buffering off 后，Nginx 不再管理响应体生命周期，很多默认机制会失效或冲突：

CPA Update - Secure CLI Proxy API Maintenance

安全更新和维护 CLI Proxy API（CPA）部署与配置。用于 CPA 镜像升级、配置变更、认证目录兼容修复、上线验证与回滚。适用于用户提到“CPA 更新/升级/配置改了/容器重建/回滚”等场景。

下载

• gzip 必须关闭：gzip off; —— 因为 gzip 要求响应完整才能压缩，流式转发无法满足
• 缓存必须关闭：proxy_cache off; —— 防止 Nginx 尝试缓存未结束的 chunked 响应，引发 502 或截断
• HTTP/1.1 和 Connection 头必须显式设置：proxy_http_version 1.1; + proxy_set_header Connection ''; —— 保证长连接不被降级，避免中间代理（如 CDN）误关连接
• 超时必须拉长：proxy_read_timeout 300; —— SSE 或 LLM 场景下服务可能几十秒才发下一个 event/token，太短会主动断连

底层传输行为要显式加固

仅靠 proxy_buffering off 不足以保障 TCP 层不积压，还需干预内核和 socket 行为：

• 禁用 Nagle 算法：tcp_nodelay on; —— 防止小包合并，确保每个 chunk 立即发出
• 保留 proxy_buffer_size：proxy_buffer_size 4k; —— 它专用于缓存响应头，即使 buffering 关闭也必须存在，否则 header 写不全导致 502
• 检查内核 rmem_max：高并发流式连接下，Linux socket 接收缓冲区可能成为瓶颈，必要时调大 net.core.rmem_max

Kubernetes Ingress 中的正确写法

Ingress-nginx 不读取 nginx.conf，必须用 annotation，且值必须是字符串：

• nginx.ingress.kubernetes.io/proxy-buffering: "off"
• nginx.ingress.kubernetes.io/proxy-http-version: "1.1"

• nginx.ingress.kubernetes.io/configuration-snippet: |<br>  proxy_set_header Connection '';<br>  gzip off;<br>  proxy_read_timeout 300;

注意：annotation 中不能写 proxy_buffering off; 这类语句，必须用 configuration-snippet 注入原生指令。