缓冲 · XB 现场笔记

响应缓冲在资源预算内吸收两端速度差

Tue, 07 Dec 2027 00:00:00 +0000

响应缓冲允许 nginx 以一种速度读取上游，同时以另一种速度向客户端交付数据。开启 proxy_buffering on 后，nginx 使用配置的内存缓冲区，也可以把大响应的一部分写入临时文件。它不必先收齐完整响应才发送第一批字节。两条连接能在多大程度上独立推进，取决于可用缓冲容量，而不是“开启”这两个字就能无限解耦。

坏掉的样子

“慢客户端永远不会阻塞后端”是错误承诺。内存缓冲、临时文件上限、磁盘吞吐和套接字缓冲都有限。当 nginx 无法继续吸收数据，上游仍然可能受到反压。禁用临时文件缓冲，也不等于关闭响应缓冲；它只是移除了一个等待数据的存储位置，使容量边界更容易到达。应明确哪个容量耗尽，而不是把所有等待都叫作后端慢。

缓冲还可能影响端点的延迟预期。虽然不要求收完整份响应，小事件仍可能先累积，之后才对客户端可见。流式端点应明确选择响应缓冲策略，并通过完整链路验证事件可见时间。即使关闭 nginx 响应缓冲，应用自身缓冲、压缩、TLS 和其他中间层仍会影响交付。因此，修改一条指令不能代替实际观察用户什么时候收到每个事件。

资源交换发生在代理层。把响应写入临时文件，可以让后端较早结束工作，但在客户端慢慢读取期间会占用临时存储和磁盘读写能力。为每条连接扩大内存缓冲，则可能在高并发下产生另一类容量问题。真正需要决定的是：面对实际工作负载，代理应该吸收多少数据、承担多少等待，而不是只凭单个缓冲值看起来更大来判断性能。

快速验证

下文集成实验的结果保留自历史运行记录；本次修订没有重新执行该实验，不能将这些记录当成本次环境的新实测。

将脚本保存为 check-response-buffering.py，准备 Python、Docker、固定镜像和足够的临时磁盘空间后运行。记录环境为 Linux arm64 上的 nginx 1.28.0。专用后端提供受控响应开关和进度计数，nginx 仅通过宿主回环监听。实验会传输三份 32 MiB 正文，完成后清理自己的资源，不使用现有业务后端：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
import hashlib
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
from urllib.parse import urlsplit,parse_qs
import json,socket,threading
lock=threading.Lock();state={};gates={};chunk=b'x'*65536;total=32*1024*1024
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 parsed=urlsplit(self.path);path=parsed.path
 if path=='/state':
 with lock:data=json.dumps(state).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(data)));self.end_headers();self.wfile.write(data);return
 if path=='/release':
 target=parse_qs(parsed.query)['path'][0]
 with lock:gates[target].set()
 self.send_response(204);self.end_headers();return
 gated=path.startswith('/early-');size=2*len(chunk) if gated else total
 with lock:state[path]={'written':0,'done':False};gates[path]=threading.Event()
 self.connection.setsockopt(socket.SOL_SOCKET,socket.SO_SNDBUF,65536)
 self.send_response(200);self.send_header('Content-Length',str(size));self.end_headers()
 for offset in range(0,size,len(chunk)):
 self.wfile.write(chunk)
 with lock:state[path]['written']=offset+len(chunk)
 if gated and offset==0:assert gates[path].wait(15)
 with lock:state[path]['done']=True
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
locations='''
location /early-on { proxy_buffering on; proxy_pass http://backend:8081; }
location /early-off { proxy_buffering off; proxy_pass http://backend:8081; }
location /large-on { proxy_buffering on; proxy_pass http://backend:8081; }
location /large-off { proxy_buffering off; proxy_pass http://backend:8081; }
location /large-nodisk { proxy_buffering on; proxy_max_temp_file_size 0; proxy_pass http://backend:8081; }
location / { proxy_pass http://backend:8081; }
'''
extra='''
proxy_buffer_size 4k; proxy_buffers 4 4k; proxy_busy_buffers_size 8k;
proxy_temp_file_write_size 8k; proxy_max_temp_file_size 64m; proxy_temp_path /tmp/proxy;
'''
with lab(config(locations,extra),backend=backend) as (proxy,request):
 results={}
 def state():return json.loads(request('/state')[2])
 for mode in ('on','off'):
 path='/early-'+mode;connection=http.client.HTTPConnection('127.0.0.1',request.port,timeout=10)
 connection.request('GET',path);response=connection.getresponse();first=response.read(1024)
 snapshot=state()[path];assert response.status==200 and first==b'x'*1024 and not snapshot['done']
 assert request('/release?path='+path)[0]==204
 rest=response.read();connection.close();assert first+rest==b'x'*(2*65536)
 results[path]={'first_bytes_before_backend_completion':len(first),'backend_written_at_first_read':snapshot['written']}
 total=32*1024*1024;expected=hashlib.sha256(b'x'*total).hexdigest()
 for mode in ('on','off','nodisk'):
 path='/large-'+mode;sock=socket.socket();sock.setsockopt(socket.SOL_SOCKET,socket.SO_RCVBUF,65536)
 sock.settimeout(20);sock.connect(('127.0.0.1',request.port))
 connection=http.client.HTTPConnection('127.0.0.1',request.port,timeout=20);connection.sock=sock
 connection.request('GET',path);response=connection.getresponse();assert response.status==200
 wait(lambda:state().get(path,{}).get('written',0)>0)
 if mode=='on':wait(lambda:state()[path]['done'])
 else:
 previous=-1;stable_since=time.monotonic();deadline=time.monotonic()+10
 while time.monotonic()<deadline:
 current=state()[path];assert not current['done'],current
 if current['written']!=previous:previous=current['written'];stable_since=time.monotonic()
 if time.monotonic()-stable_since>1:break
 time.sleep(.05)
 else:raise AssertionError('backend did not reach observable backpressure')
 before=state()[path]
 if mode!='on':assert 0<before['written']<total
 sock.setsockopt(socket.SOL_SOCKET,socket.SO_RCVBUF,1024*1024)
 digest=hashlib.sha256();received=0
 while block:=response.read(1024*1024):digest.update(block);received+=len(block)
 connection.close();wait(lambda:state()[path]['done'])
 assert received==total and digest.hexdigest()==expected
 results[path]={'before_client_drain':before,'received_bytes':received,'sha256':digest.hexdigest()}
 log=docker('exec',proxy,'cat','/tmp/error.log').stdout
 spills=[line for line in log.splitlines() if 'buffered to a temporary file' in line]
 assert any('/large-on ' in line for line in spills),log
 assert not any('/large-off ' in line or '/large-nodisk ' in line for line in spills)
 results['temporary_file_used_for_large_on']=True
 print(json.dumps(results,sort_keys=True))

首先，后端为一个 131,072 字节响应写出 65,536 字节，然后等待显式放行。无论响应缓冲开启还是关闭，客户端都能在后端尚未完成时读到 1,024 字节正文。脚本随后才放行后一半，并检查完整响应。这直接否定了“开启响应缓冲就一定等上游整份响应完成才交付”的说法；受控开关把响应尚未完成这一事实固定下来。

接着，客户端收到 32 MiB 响应头后暂停消费正文。开启响应缓冲、临时文件上限设为 64 MiB 时，后端在客户端继续读取前记录自己已经写完整份响应。nginx 错误日志同时确认该响应使用了临时文件。后端进度和真实写盘日志共同支持结论，不能只根据某次请求耗时短，就推断一定发生了磁盘缓冲。

关闭响应缓冲时，客户端保持暂停，后端完成写入的计数停在 32 MiB 以下。实验要求计数在受控观察区间内保持不变，然后恢复客户端读取；后端随后完成，完整摘要也匹配。另一个对照保留响应缓冲，但设置 proxy_max_temp_file_size 0，同样在客户端恢复消费前出现可观察反压，说明开启内存缓冲也不提供无限吸收能力。

中途停住的具体字节数会随套接字和平台行为变化。它们是本次观察结果，不是推荐缓冲大小，也不是跨平台固定阈值。关键差别是：客户端暂停时，有一条路径完成了响应生产，另外两条受限路径没有。最终三条路径都交付恰好 33,554,432 字节，并通过同一个预期 SHA-256 摘要检查，证明恢复读取后内容完整。

为缓冲分配预算，并验证可见进度

proxy_buffer_size 处理上游响应的第一部分，通常包含响应头；proxy_buffers 配置其他响应缓冲区；临时文件指令控制这里未缓存响应的磁盘使用。不要把这些限制误当成最大可接受响应长度。客户端读取后释放容量，较大响应可以继续传输，并不是只要超过内存缓冲区，就必然被拒绝或要求一次性保存到内存。

上游可以通过 X-Accel-Buffering 请求改变响应缓冲，除非 nginx 配置为忽略该响应头。当 location 的预期策略似乎没有生效，应检查应用是否发出了这个控制信号。请求正文缓冲是另一项设置，不会被这个响应控制改变；定位问题时必须先确定受到影响的是上传方向，还是返回客户端的方向。

对于普通下载，应同时考虑后端占用、代理磁盘使用和客户端完成时间。对于渐进事件，应测量每个事件什么时候可见，并加入慢读客户端。一次快速本地传输，既不能证明已经隔离慢客户端负载，也不能证明流式延迟满足应用契约。这里的受控暂停和完成计数用于揭示边界，生产容量仍应依据真实响应大小与并发分布确定。

来源

nginx proxy module，响应缓冲区、临时文件与 X-Accel-Buffering 控制，已核验 2026-10-15。
nginx reverse proxy guide，缓冲转发与向客户端同步转发，已核验 2026-10-15。

请求缓冲决定后端何时收到上传正文

Tue, 13 Apr 2027 00:00:00 +0000

一次上传经过两条连接：客户端到 nginx，以及 nginx 到应用。proxy_request_buffering on 会先读完客户端请求正文，再把该请求发送给上游。关闭它后，nginx 可以随着正文到达逐步转发。这个选择改变应用何时开始占用资源，却不会创造无限容量，也不会使慢发送方消失。应先明确应用是否需要边收边处理，再决定正文在哪一层等待。

坏掉的样子

常见错误是关错指令。proxy_buffering 控制响应，proxy_request_buffering 控制上传请求。仅关闭响应缓冲，流式上传仍可能停在代理处。反过来，如果应用原本应接收完整的小型提交，却在全站关闭请求缓冲，又没有考虑后端并发能力，慢客户端就可能长时间占住应用处理资源。两个方向的策略不能因为名称相似就混为一谈。

缓冲把资源压力转移到 nginx。请求正文超过配置的内存缓冲后，可以使用客户端正文临时存储。因此，大量并发上传会占用代理连接，并可能消耗磁盘空间或磁盘读写能力。增大某个缓冲值不能代替正文大小、上传超时、并发限制和临时文件系统容量规划。缓冲区也不需要一律扩大到能在内存中容纳完整上传。

流式转发还改变失败处理。nginx 一旦已经开始向上游发送请求正文，就不能简单把这个流式请求交给下一台服务器。应用可能已经处理前缀数据，甚至产生副作用。缓冲可以为某些重试路径保留正文，但不能让原本不安全的业务操作突然变得可安全重放。是否允许重试，还取决于实际方法、应用语义以及已经完成的工作。

快速验证

下文集成实验的结果保留自历史运行记录；本次修订没有重新执行该实验，不能将这些记录当成本次环境的新实测。

将脚本保存为 check-upload.py，先取得其中固定摘要的镜像，再用宿主 Python 和 Docker 执行。记录环境为 Linux arm64 上的 nginx 1.28.0、Python 3.11.16 容器。脚本建立专用后端网络，只把 nginx 发布到宿主回环地址，最后清理自己的容器、镜像标签和网络；已有服务不参与实验：

from contextlib import contextmanager
from pathlib import Path
from tempfile import TemporaryDirectory
import http.client,json,socket,subprocess,time,uuid

NGINX='nginx@sha256:552e7481ca93ffccd046aa658dbbed22caefbc09c66fa7cd247cbb90b8a5c609'
PYTHON='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result
def wait(predicate):
 deadline=time.monotonic()+15
 while time.monotonic()<deadline:
 try:
 if predicate():return
 except OSError:pass
 time.sleep(.1)
 raise AssertionError('fixture did not become ready')

@contextmanager
def lab(configuration,files=None,backend=None):
 name='xbcatm-nginx-'+uuid.uuid4().hex[:10];tags=[name+':proxy',name+':backend'];containers=[name+'-proxy',name+'-backend']
 try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'files').mkdir();(root/'nginx.conf').write_text(configuration)
 for path,content in (files or {}).items():
 target=root/'files'/path;target.parent.mkdir(parents=True,exist_ok=True)
 target.write_bytes(content if isinstance(content,bytes) else content.encode())
 docker('network','create',name)
 if backend is not None:
 (root/'backend.py').write_text(backend)
 (root/'backend.Dockerfile').write_text(f'FROM {PYTHON}\nCOPY backend.py /backend.py\nCMD ["python", "/backend.py"]\n')
 docker('build','--network','none','-f',str(root/'backend.Dockerfile'),'-t',tags[1],str(root))
 docker('run','-d','--name',containers[1],'--network',name,'--network-alias','backend',tags[1])
 wait(lambda:docker('exec',containers[1],'python','-c','import socket;s=socket.create_connection(("127.0.0.1",8081),timeout=.5);s.close()',check=False).returncode==0)
 (root/'Dockerfile').write_text(f'FROM {NGINX}\nCOPY nginx.conf /etc/nginx/nginx.conf\nCOPY files /srv\n')
 docker('build','--network','none','-t',tags[0],str(root))
 docker('run','--rm','--network',name,tags[0],'nginx','-t')
 docker('run','-d','--name',containers[0],'--network',name,'-p','127.0.0.1::8080',tags[0])
 details=json.loads(docker('inspect',containers[0]).stdout)[0]
 binding=details['NetworkSettings']['Ports']['8080/tcp'][0];assert binding['HostIp']=='127.0.0.1';port=int(binding['HostPort'])
 def ready():
 connection=socket.create_connection(('127.0.0.1',port),timeout=.5);connection.close();return True
 wait(ready)
 def request(path,method='GET',headers=None,body=None):
 connection=http.client.HTTPConnection('127.0.0.1',port,timeout=5)
 try:
 connection.request(method,path,body=body,headers=headers or {})
 response=connection.getresponse();return response.status,{k.lower():v for k,v in response.getheaders()},response.read()
 finally:connection.close()
 request.port=port
 yield containers[0],request
 finally:
 docker('rm','-f',*containers,check=False);docker('image','rm',*tags,check=False);docker('network','rm',name,check=False)

def config(locations,extra=''):
 return 'worker_processes 1;\nerror_log /tmp/error.log notice;\nevents {}\nhttp {\naccess_log off;\n'+extra+'\nserver { listen 8080; root /srv;\n'+locations+'\n}\n}\n'
import hashlib
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
import hashlib,json,threading
state={};lock=threading.Lock()
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def reply(self,data):
 data=json.dumps(data).encode();self.send_response(200)
 self.send_header('Content-Length',str(len(data)));self.end_headers();self.wfile.write(data)
 def do_GET(self):
 with lock:self.reply(dict(state))
 def do_POST(self):
 length=int(self.headers['Content-Length'])
 with lock:state[self.path]={'entered':True,'bytes':0}
 first=self.rfile.read(1)
 with lock:state[self.path]['bytes']=len(first)
 body=first+self.rfile.read(length-1)
 with lock:state[self.path]['bytes']=len(body)
 self.reply({'length':len(body),'sha256':hashlib.sha256(body).hexdigest()})
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
locations='''
location /on { proxy_request_buffering on; proxy_pass http://backend:8081; }
location /off { proxy_request_buffering off; proxy_pass http://backend:8081; }
location /state { proxy_pass http://backend:8081; }
'''
with lab(config(locations,'client_max_body_size 1m; proxy_http_version 1.1;'),backend=backend) as (_,request):
 payload=b'x'*65536;results={}
 def state():return json.loads(request('/state')[2])
 for mode in ('on','off'):
 connection=http.client.HTTPConnection('127.0.0.1',request.port,timeout=10)
 connection.putrequest('POST','/'+mode);connection.putheader('Content-Length',str(len(payload)))
 connection.endheaders();connection.send(payload[:1024])
 if mode=='off':wait(lambda:state().get('/off',{}).get('bytes')==1)
 else:
 until=time.monotonic()+1
 while time.monotonic()<until:
 assert '/on' not in state();time.sleep(.05)
 before=state().get('/'+mode)
 connection.send(payload[1024:]);response=connection.getresponse();data=json.loads(response.read());connection.close()
 assert response.status==200 and data=={'length':65536,'sha256':hashlib.sha256(payload).hexdigest()}
 results[mode]={'before_completion':before,'result':data}
 connection=http.client.HTTPConnection('127.0.0.1',request.port,timeout=5)
 connection.putrequest('POST','/off-too-large');connection.putheader('Content-Length',str(2*1024*1024))
 connection.endheaders();response=connection.getresponse();response.read();connection.close()
 assert response.status==413 and '/off-too-large' not in state()
 results['oversize_status']=response.status
 print(json.dumps(results,sort_keys=True))

客户端声明正文共 65,536 字节，起初只发送 1,024 字节。开启请求缓冲时，在受控暂停期间反复读取后端状态，都看不到上传处理器被进入。客户端已经开始发送，但应用还没有被要求消费不完整正文。直接观察后端状态，比只比较整个请求耗时更能说明等待发生在哪一层，也避免把一次快速响应误当成流式处理证据。

关闭请求缓冲时，后端在客户端补齐正文之前就进入处理器，并记录已经读到第一个字节，随后等待声明长度中的剩余部分。这验证的是真实上传过程中的转发，而不仅是 nginx 能接受某行配置。后端故意采用简单读取顺序，使“已经开始处理、尚未收完正文”这个中间状态可以明确观察和断言。

发送剩余数据后，两种模式都返回长度 65,536，并得到同一个预期 SHA-256 摘要。因此，虽然处理时机不同，本次缓冲与流式路径都保留了原正文。断言核对实际收到的字节，不只检查成功状态码。它也不代表所有应用解析器、数据保存操作或断线恢复策略已经验证；这些需要根据真实端点的行为另行覆盖。

另一个请求在一兆字节限制下声明两兆字节正文。客户端尚未发送正文，nginx 就返回 413，后端也没有对应处理记录。这是代理执行正文大小策略，关闭请求缓冲并不会关闭这项限制。实验刻意使用已知 Content-Length 的定长消息，让拒绝时机可以直接观察，不把未知长度流的接收过程混进这一结论。

先确定上传契约，再调整缓冲

如果应用工作资源稀缺，希望让慢发送方先在代理等待，且代理存储成本可接受，可以选择缓冲上传。如果应用必须逐步处理传入数据，就选择流式路径，同时承担后端资源占用和不完整提交的处理责任。两种模式都不保证写入方永远不会被下游容量限制；缓冲只能吸收一定程度的速度差。

请求和响应策略应分别决定。某个端点可以先接收缓冲上传，再流式返回进度；也可以流式接收上传，最后返回很小的缓冲结果。上游响应中的 X-Accel-Buffering 控制响应缓冲，不能取代这里验证的请求正文策略。检查配置时应明确每条指令影响哪条数据流。

扩展实验时，还要检查消息分帧和上游协议。在 nginx 1.28.0 中，客户端采用 HTTP/1.1 chunked 上传时，需要启用 HTTP/1.1 代理，才能避免该路径强制缓冲。这里显式选择了上游 HTTP/1.1，但实际测试的是定长正文。如果真实端点还接受分块正文或需要处理中途断开，就应针对这些契约补充验证，不能从本次定长上传结果直接推断。

来源

nginx proxy module，请求缓冲、流式请求重放限制与上游 HTTP 版本，已核验 2026-10-15。
nginx HTTP core module，请求正文大小限制、内存缓冲与临时存储，已核验 2026-10-15。
RFC 9110 HTTP Semantics，Content-Length 与 413 响应的语义，已核验 2026-10-15。

缓冲 · XB 现场笔记

响应缓冲在资源预算内吸收两端速度差

坏掉的样子

快速验证

为缓冲分配预算，并验证可见进度

延伸阅读

来源

请求缓冲决定后端何时收到上传正文

坏掉的样子

快速验证

先确定上传契约，再调整缓冲

来源