每天一个开源项目#162 NGINX:流式响应背后的缓冲、背压与重试

日期:2026-11-20 GitHub Trending 日榜第 7 位;榜单采集时间为北京时间 16:00:33。

模型已经生成了文字,浏览器却迟迟没有显示,过一会儿又一口气出现一大段。排查流式接口时,很容易先怀疑推理服务,其实中间的反向代理也可能改变数据到达的节奏。

NGINX 的 proxy_buffering off 经常出现在这类问题的解决方案里。但关掉响应缓冲以后,上游、代理和慢客户端会重新耦合;如果连接断在半途,代理也不能把另一台服务器的输出接上来,假装这是同一次生成。

顺着这个问题读 NGINX,比背诵"高并发、事件驱动"更有收获。它把等待、数据暂存、连接退出和重试拆成了明确的状态。本文围绕普通 HTTP 反向代理展开,重点看流式响应,不把 HTTP/2、HTTP/3 和 WebSocket 的细节混在一条调用链里。

📋 项目概览

项目 内容
主仓库 nginx/nginx
项目定位 Web 服务器、反向代理、负载均衡与内容缓存
核心实现 C;模块化配置与事件驱动的请求处理
进程组织 master 管理配置及进程,worker 处理连接和请求
许可 BSD 两条款风格许可;分发时保留相应版权与免责声明
本文关注 HTTP 代理的两类缓冲、事件续跑、流式背压、失败重试与配置重载
示例版本 NGINX 1.31.9,普通用户权限、本地回环端口

仓库 README 把模块、配置和运行进程分开介绍。这个划分很实用:装了 NGINX,不代表所有模块都可用;同样一段配置,能否解析,也取决于二进制编译了什么。

源码树的 src/core 负责核心对象和初始化,src/event 放事件框架,src/os/unix 处理 Unix 进程与平台接口,HTTP 主体位于 src/http。对于代理请求,关键边界是 ngx_http_proxy_module.c 与 ngx_http_upstream.c:前者懂 HTTP 代理的请求构造,后者组织连接、收发、超时和上游生命周期。

🔥 为什么值得关注

许多 AI 应用把模型服务部署在代理后面,前端通过 SSE 接收增量结果。页面体验取决于整条链路:应用是否及时 flush,代理是否暂存响应,中间是否还有压缩或缓存层,客户端有没有把小块数据立即呈现出来。

NGINX 值得读的地方,是它没有把这些问题塞进一个"流式模式"开关。上传缓冲和下载缓冲各有开关;读超时和整个任务的业务截止时间不是一回事;把失败请求换到另一台上游,与保证业务只执行一次也不是一回事。配置项看起来分散,底下对应的恰好是不同的资源与失败边界。

例如,开启响应缓冲时,代理可以较快读完上游结果,再按照客户端的速度慢慢发送。后端连接因此有机会更早释放,代价是代理需要承担内存和可能的临时文件开销。关闭缓冲能减少这一级主动积攒数据,但慢客户端的影响也更容易传回上游。

这两种选择都有合理用途。下载普通报告文件和显示逐字生成的答案,对延迟与资源占用的要求本来就不同。把所有接口统一改成不缓冲,往往只是把一个局部体验问题变成另一种容量问题。

🏗️ 核心特性

请求缓冲与响应缓冲分属两个方向

proxy_request_buffering 控制从客户端接收请求体的方式;proxy_buffering 控制从上游接收响应的方式。代理模块在合并配置时,两者默认都开启,但作用不同。

客户端上传大文件时,请求缓冲能先由代理接收请求体,再交给后端。关闭以后,满足协议等条件时,请求体可以边读边转发,后端需要陪伴整个上传过程。特别是 chunked 请求,源码还会检查代理使用的 HTTP 版本等条件,不能只看见配置里写了 off 就认定一定没有请求体缓冲。

SSE 是响应方向的问题。一个没有请求体的 GET 流式接口,通常首先要关注 proxy_buffering,不是把两个开关一起关掉。POST 形式的流式聊天也可以保留输入缓冲,同时关闭输出缓冲;输入 JSON 的接收方式和输出事件的展示节奏没有必要绑定。

"不缓冲"仍然需要缓冲区

NGINX 的非缓冲响应路径仍持有 u->buffer,并通过 out_bufs、busy_bufs、free_bufs 管理待发送数据。读 socket 与写 socket 之间需要一块工作内存,否则代理连分段收发都做不到。

proxy_buffering off 的意思,是不再按普通响应缓冲路径去积极收取和暂存整个响应,不是代理完全不占内存,也不是一个上游 token 必然对应一个 TCP 包。HTTP 分帧、TLS、操作系统和浏览器都可能合并数据。

官方代理模块文档 还说明,非缓冲模式一次从上游读取的数据大小受 proxy_buffer_size 约束。这比"关闭所有缓存"准确得多:响应缓冲、HTTP 内容缓存和网络缓冲并不是同一个概念。

上游响应头可以参与控制

NGINX 可以处理上游返回的 X-Accel-Buffering: no 或 yes。源码的 ngx_http_upstream_process_buffering() 先检查是否忽略该头,再根据配置是否允许改变缓冲,修改当前上游请求的 buffering 标志。

因此,排查配置时既要看 location,也要看应用实际返回的头。若运维使用 proxy_ignore_headers 忽略了 X-Accel-Buffering,应用声明关闭缓冲也不会按原意生效。反过来,允许上游控制缓冲,意味着代理把这部分行为选择交给了应用,不能再只凭静态配置判断最终模式。

优雅重载不等于替换正在运行的请求

nginx -s reload 通知 master 重读配置。新配置初始化成功后,master 启动新 worker,再要求旧 worker 优雅退出;初始化失败则保留旧配置周期。

旧 worker 上已有的连接不会凭空搬进新 worker。长连接可能使新旧进程同时存在一段时间,所以一次 reload 不能证明所有活跃请求都已经采用新配置。这个边界对 SSE 特别重要:验证新配置应建立新连接,而不是只盯着一条原先就存在的流。

🔬 技术架构深度解析

从进程循环到上游回调

下面的流程图限定为 Unix 上的普通 HTTP 代理,省略 TLS 握手、HTTP/2 和缓存命中分支。

text 复制代码
master:读取配置 / 管理 worker / 处理重载信号
    │
    ├─ 新配置成功 → 启动新 worker → 通知旧 worker 优雅退出
    └─ 新配置失败 → 保留旧配置周期

worker
  ngx_worker_process_cycle()
    └─ ngx_process_events_and_timers()
         ├─ 等待平台事件后端:Linux epoll / BSD、macOS kqueue 等
         ├─ 处理 posted accept events
         ├─ 处理到期定时器
         └─ 处理普通 posted events
                │
           HTTP 请求解析
                ↓
       ngx_http_core_run_phases()
                ↓
       ngx_http_proxy_handler()
         ├─ 创建 r->upstream
         ├─ 注入构造请求、解析响应头等回调
         └─ 读取请求体 → ngx_http_upstream_init()
                ↓
      连接上游 → 发送请求 → 接收响应头
                ↓
       ngx_http_upstream_send_response()
         ├─ buffering=1 → event_pipe / 内存链 / 可能的临时文件
         └─ buffering=0 → 上游读回调 + 下游写回调 / 有界工作缓冲
                ↓
        HTTP 输出过滤器 → 客户端连接

开发指南 对事件和 HTTP 请求生命周期有更完整的介绍。读代码时尤其要留意:这张图表达的是逻辑推进,不是一条从头阻塞到尾的函数栈。

worker 把等待交还给事件循环

ngx_worker_process_cycle() 的主循环调用 ngx_process_events_and_timers()。后者先计算等待事件的时间界限,进入平台事件处理,再处理 posted accept events、到期定时器和普通 posted events。事件后端也可能直接分发处理,因此不能把 posted 队列误认为唯一的回调来源。

连接没有数据可读时,请求会留下状态与回调,等待下一次就绪通知。大量处于等待中的连接因此不需要各自占用一个阻塞线程。这个模型并不意味着 worker 可以随意执行耗时同步任务;如果模块长时间占着 worker 的执行线程,同一个 worker 上其他连接的推进也会受影响。

"NGINX 用 epoll"也需要加上平台条件。源码中有多种事件后端,在 macOS 上运行示例不代表验证了 Linux epoll 路径。事件抽象复用了调用接口,具体能力和行为仍由平台实现决定。

请求阶段表保存推进位置

ngx_http_core_run_phases() 从主配置中取出 phase_engine.handlers,使用请求对象上的 phase_handler 索引调用阶段 checker。ngx_http_handler() 还会把写事件处理器设置成阶段运行函数。

这个设计让请求可以暂停,再从保存的阶段继续。不能把 phase checker 的返回值,直接等同于某个业务模块 handler 的返回值;checker 还承担阶段推进和完成判断。只看宏名字,很容易把这里读反。

对于代理内容处理器,ngx_http_proxy_handler() 创建 upstream 对象,并挂入 create_request、reinit_request、process_header、abort_request、finalize_request 等回调。随后通过 ngx_http_read_client_request_body() 衔接到 upstream 初始化。

协议细节和通用连接状态机因此有了分工。代理模块知道如何生成上游 HTTP 请求、如何解析状态行;upstream 层知道什么时候连接、等待、重试、回收。新增协议处理不需要复制整套连接生命周期,但回调必须遵守这套生命周期的约束。

两条响应路径,承担不同的等待成本

开启响应缓冲时,ngx_http_upstream_send_response() 为 event_pipe 设置 upstream、downstream、缓冲数量、busy buffer 大小和临时文件限制。它既要尽可能从上游读,也要按下游可写程度发送。

这不是必须等整个响应收完才给客户端第一个字节。缓冲模式仍可边收边发,只是代理允许在两端速度不一致时暂存更多数据。若内存装不下且相关条件允许,部分内容还可落入临时文件。把响应缓冲直接叫作"整包返回",会误导后续排查。

关闭响应缓冲时,upstream 层分别设置上游读事件处理器和下游写事件处理器。公共处理函数先尝试把输出链交给 ngx_http_output_filter(),回收已经发送的链,再检查工作缓冲还有多少空位、上游是否可读。recv() 返回 NGX_AGAIN 时就交还控制,而不是在循环里忙等。

当客户端很慢时,输出链不能及时回收,可继续读取的空间会减少。代理读得慢,上游 TCP 发送也可能逐渐受限。这就是背压沿连接传播的一种具体方式;关闭响应缓冲没有消灭等待,只是改变了等待落在哪一端,以及代理愿意承担多少中间存储。

超时约束的是停顿,不是整段生成时长

非缓冲路径会在上游读事件处于等待状态时添加 read_timeout 定时器,事件重新就绪时删除相应定时器。proxy_read_timeout 文档 明确说,它约束相邻两次读取之间的等待,不是传完整个响应的总时间。

一个持续发数据的长响应,可以运行超过这个配置值;一个还没开始输出、一直沉默的模型调用,则可能被读超时截断。应用心跳能帮助避免长时间无数据,但不能替代业务层的总耗时预算、取消和错误反馈。

同时,代理上游读超时与客户端读超时是两个计时器,配置任何一个都不会自动修改另一个。排查时要记录谁先关闭连接,再决定调整哪个环节。

重试不能接续半条响应,也不能代替业务幂等

ngx_http_upstream_next() 会综合剩余尝试次数、允许的失败类型、重试时间窗口、请求是否已经发送以及请求体能否重新发送,决定是否进入下一个上游。

其中有两项约束直接影响 AI 与业务接口:

  • POST、LOCK、PATCH 已发往上游后,源码会加入非幂等失败标记;没有显式允许 non_idempotent,不会按普通可重试请求那样继续。
  • 请求体以非缓冲方式转发且请求已经发出时,无法假设本地仍保存着可完整重放的输入,这也是阻止继续重试的条件。

重试指令文档 另一个重要边界是:只有还没有向客户端发送内容时,才有换上游的空间。已经输出半段 SSE,后端再故障,代理不能把另一台服务器从头生成的文字直接拼上。

官方 nginx-tests 的 proxy_non_idempotent.t 把 GET 和 POST 放在同一种后端断开情形中,检查默认行为与显式启用 non_idempotent 后的差别。它说明维护者在测试中保护了这条语义,不代表代理能识别订单号、任务 ID 或一次模型请求的扣费状态。

对可能产生副作用的接口,更稳妥的做法是由应用使用幂等键、任务查询和明确的重试协议。代理只知道传输状态,不知道后端是否已经完成数据库提交。

容量规划要把两侧连接都算进去

worker_connections 限制的是 worker 的连接容量,不是"允许多少客户端"的直接承诺。源码按该配置分配连接对象及读写事件数组,并检查打开文件资源限制。

普通反向代理通常同时持有客户端连接与上游连接,监听、空闲连接等也有开销;HTTP/2 多路复用和连接复用又会改变对应关系。所以不能简单用 worker 数量乘这个值,就当作能稳定承载的业务并发数。

对流式生成,更有用的观察是活跃流数量、平均持续时间、两端连接占用、输出队列、内存、文件描述符和上游可接纳的任务数。仅仅把连接上限调高,并不会让模型服务多出推理容量。

📖 README 核心内容摘要

README 有几条会直接影响落地:

  1. NGINX 由模块组成。静态模块随二进制构建,动态模块可以通过配置加载;nginx -V 能查看编译参数,但不应被当作所有动态模块的运行时清单。
  2. 配置文件中的指令来自模块。遇到 unknown directive,先检查模块和构建选项,不要只反复修改缩进。
  3. master 与 worker 的分工之外,还存在共享内存区域等跨进程机制。不能把"多进程"理解为所有状态绝不共享,也不能假定普通请求对象天然跨 worker 可见。
  4. 官方提供二进制安装说明,也提供源码构建路径。Git 仓库的构建入口是 auto/configure;成功后用 make,生成的二进制在 objs/nginx。

README 对 stable 与 mainline 的说明是发布路线的区别,不是给每个新功能做兼容承诺。生产部署还要结合模块、依赖库与安全更新策略。下面固定一个版本做本地功能示例,避免把构建示例误写成推荐所有环境使用的部署方案。

许可证允许在保留所要求声明的条件下修改与再分发源码或二进制。开源仓库与商业发行版的能力也应分开看,不能把商业文档中的选项不加区分地搬进开源配置。

🚀 快速上手

这个例子只做一件事:让 Python 后端发送三个 SSE 事件,经 NGINX 代理后逐段读取。需要 Git、C 编译器、make、Python 3 和 curl;使用空闲的本地端口 18080、18081。所有监听都限制在回环地址,不需要 root,也不安装系统服务。

1. 构建一个最小演示二进制

bash 复制代码
git clone --depth 1 --branch release-1.31.9 https://github.com/nginx/nginx.git
cd nginx
auto/configure --without-http_rewrite_module --without-http_gzip_module
make -j2
./objs/nginx -h
mkdir -p demo/logs

这里关闭 rewrite 和 gzip,是为了减少演示构建依赖;所以不要再往示例配置加入 rewrite 模块的 return 指令,也不要据此认为生产服务不需要压缩或重写。HTTPS 等额外功能需要相应模块与依赖,这个二进制只演示本地 HTTP 代理。

2. 保存一个真正 flush 的后端

在仓库根目录创建 demo/backend.py:

python 复制代码
from http.server import BaseHTTPRequestHandler, HTTPServer
import time


class Handler(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"

    def do_GET(self):
        self.send_response(200)
        self.send_header("Content-Type", "text/event-stream")
        self.send_header("Cache-Control", "no-cache")
        self.send_header("Connection", "close")
        self.end_headers()
        self.close_connection = True
        for i in range(3):
            self.wfile.write(f"data: event-{i}\n\n".encode())
            self.wfile.flush()
            time.sleep(0.2)


HTTPServer(("127.0.0.1", 18081), Handler).serve_forever()

它在每个事件后写入空行并 flush,最终关闭连接。这个单线程演示服务器不是生产 SSE 服务:没有并发处理、鉴权、断线恢复和客户端取消等业务逻辑。

3. 保存代理配置

在仓库根目录创建 demo/nginx.conf:

nginx 复制代码
worker_processes 1;
pid logs/nginx.pid;
error_log logs/error.log notice;
events { worker_connections 128; }
http {
    access_log logs/access.log;
    server {
        listen 127.0.0.1:18080;
        server_name localhost;
        location /events {
            proxy_pass http://127.0.0.1:18081;
            proxy_http_version 1.1;
            proxy_set_header Connection "";
            proxy_buffering off;
            proxy_read_timeout 5s;
        }
    }
}

这里没有给 proxy_pass 增加 URI 部分,/events 会转发给后端;Python 示例对 GET 路径不做区分。Connection "" 表示不向上游转发该头,不代表这段配置已经建立了 upstream keepalive 连接池。后端仍明确在响应后关闭连接。

4. 启动、读取和退出

以下命令均在 nginx 仓库根目录运行。终端 A 启动后端:

bash 复制代码
python3 demo/backend.py

终端 B 检查并启动代理,然后读取事件:

bash 复制代码
./objs/nginx -p "$PWD/demo/" -c "$PWD/demo/nginx.conf" -t
./objs/nginx -p "$PWD/demo/" -c "$PWD/demo/nginx.conf"
curl -N http://127.0.0.1:18080/events

预期响应正文如下,每个事件之间有一个空行:

text 复制代码
data: event-0

data: event-1

data: event-2

curl -N 关闭的是 curl 自己的输出缓冲,它不会替你修改代理配置。本地功能运行中,配置检查通过,并逐段读到了这三个事件;这只能说明该最小链路工作,不是并发能力或公网延迟基准。

修改配置后先运行同样的 -t 检查,再通知这个演示实例重载;结束后优雅退出:

bash 复制代码
./objs/nginx -p "$PWD/demo/" -c "$PWD/demo/nginx.conf" -s reload
./objs/nginx -p "$PWD/demo/" -c "$PWD/demo/nginx.conf" -s quit

最后在终端 A 用 Ctrl+C 关闭 Python 后端。-p 和 -c 必须与启动时一致,否则信号命令可能查找另一处 PID 文件。发送 reload 信号成功,也不等于新配置已经投入运行,仍要检查这个实例的错误日志,并用新连接验证行为。

若仍看不到逐段输出,先直连 18081/events,再经过 18080/events 对比。直连也成批出现时,优先检查应用与客户端;只有代理路径异常时,再核查匹配的 location、缓冲头和其他中间层。不要一次修改所有层,否则即便问题暂时消失,也很难知道是哪一项起作用。

📊 增长速度与社区热度

NGINX 在这份日榜中排第 7。一个成熟基础设施项目登上 Trending,说明它在该观察窗口里获得关注,但排名不能直接解释成采用量增长,更不能反推出每天新增多少 Star。

对准备引入它的团队,社区热度之外,更该检查所用分支的更新、模块兼容性和需要的故障语义。对于维护者是否保护某种行为,具体回归用例往往比总 Star 数更有参考价值。例如官方测试仓库分别覆盖了非缓冲请求体传输、失败后切换上游与非幂等请求重试;这些都是代理配置可能改变的真实行为边界。

以下是 2026-11-20 同一份日榜的完整仓库顺序:

排名 仓库
1 elementalsouls/Claude-BugHunter
2 obra/superpowers
3 HKUDS/CLI-Anything
4 jingyaogong/minimind
5 cursor/plugins
6 firecrawl/firecrawl
7 nginx/nginx
8 openvinotoolkit/openvino
9 cathrynlavery/diagram-design
10 mvanhorn/last30days-skill
11 google-labs-code/stitch-skills
12 mjmirza/app-store-compliance
13 Tracer-Cloud/opensre
14 toeverything/AFFiNE
15 XiaoYouChR/Ghost-Downloader-3
16 zhouxiaoka/autoclip

🎯 适用场景

AI 推理服务的流式出口

适合把 HTTP 路由、连接超时和 TLS 终止等网络职责与模型服务分开管理。流式路径可以单独设置响应缓冲与读超时,不必影响普通下载接口。

但 NGINX 不会解析业务事件来判断"一次生成是否成功",也不会自动持久化已经发出的 token。需要断点续传时,应用必须设计事件 ID、结果存储和重连协议;代理层负责让传输边界明确。

普通 API 与大响应下载

普通 JSON API、下载响应和慢客户端较多的接口,不必为了追求"实时"统一关闭缓冲。开启缓冲有机会减少上游被慢下游长期占用的时间,但要同时预算代理内存、临时目录空间和磁盘写入。

上传接口也需要单独讨论。关闭请求缓冲可能降低大请求进入后端的等待,却使后端更早暴露在慢上传之下,并收紧失败后的重试空间。这应是容量与协议决策,不是流式配置的附带动作。

有写入副作用的业务接口

NGINX 可以按连接错误与状态码策略切换上游,但不能证明一次写操作尚未生效。创建订单、扣费、投递消息或启动昂贵推理任务时,应先建立应用幂等与任务状态查询,再考虑允许哪些失败重试。

如果需求是"断线后透明换机器,继续同一次正在生成的答案",仅靠代理配置不合适。它还需要后端任务可寻址、输出可恢复以及客户端能识别连续性。把 non_idempotent 打开解决不了这些问题,反而可能制造重复执行。

💡 总结

NGINX 的工程价值,落在很具体的地方:worker 保存状态后让出等待,代理模块把协议回调交给通用 upstream,缓冲策略决定两端速度不一致时由谁承担成本,重试条件则限制了能够补救的失败范围。

对流式应用,建议把"请求体如何接收、响应如何暂存、允许多长无数据停顿、失败能否重放"分别回答。proxy_buffering off 只是其中一个答案。理解其余边界,才不容易把网络层的便利误当成业务层的正确性。

相关推荐
测试员周周17 分钟前
【agent评测】:真实系统演示工具调用长什么样,用例怎么设计,怎么测
前端·后端·github
吴长建先生重名了2 小时前
Laravel 项目中使用 Eloquent 实现 IM
github
网易云信2 小时前
三折叠 IM 怎么适配?云信鸿蒙 UIKit 的分栏、导航与状态保留实践
github
guuguo3 小时前
【做个开源软件】Mac 上 node 进程莫名吃掉 6G 内存?给 AI / MCP 做了个深度归因和安全回收工具
人工智能·开源·github
一条Go4 小时前
源新生代雷达 · 第 16 期
github
一条Go4 小时前
SSH 命令审核流:为什么「能执行」必须先「被批准」
后端·架构·github
杨凯凡6 小时前
IT日报|2026-11-19:Oracle Java 紧急补丁、Optimizely 供应链攻击、GitHub 安全评估升级
java·oracle·github
徐小夕7 小时前
深度拆解 Design Agent:LangChain 出品,AI 设计从「好看」走向「可用」
前端·vue.js·github
严肃小白兔8 小时前
GitHub Copilot 团队级 Agent Plugins 正式发布:插件架构、共享配置与实战
github·copilot