Nginx · XB 现场笔记

微缓存短暂复用新鲜条目，并显式合并并发未命中

Sun, 12 Mar 2028 00:00:00 +0000

微缓存让可复用响应保持很短的新鲜度寿命，常见尺度是几秒。在这个窗口里，请求同一选中表示的后续访问可以复用新鲜条目。响应可能落后于源站刚发生的更新，但不能仅因为它来自缓存，就称它在 HTTP 意义上已经过期。何时过期、是否允许提供过期内容、如何协调并发填充，是三个不同策略，需要分别定义。

坏掉的样子

TTL 短并不意味着共享响应对所有用户都安全。如果个性化请求读取或填充通用缓存条目，一个用户的表示就可能在另一个上下文里被交付。proxy_cache_bypass 根据条件禁止从缓存读取；proxy_no_cache 根据条件禁止保存响应。只控制其中一侧，可能让另一条路径不符合预期隐私边界。读取已有公开条目和保存新私有响应都需要考虑。

缓存键决定哪些请求共享响应。忽略有意义的查询参数或主机维度，可能合并不同表示；把任意变化数据全部放进键，又可能让复用失效。下面实验只有一个后端 authority，并保留包含参数的完整请求 URI。真实服务如果按租户、语言或其他输入改变内容，就必须确定自己的表示身份，不能把示例键当成适用于所有应用的通用公式。

仅仅启用缓存，也不保证冷启动突发只产生一次回源。在任何响应保存完成前，多个请求可能同时未命中同一条目。proxy_cache_lock 负责协调新条目的填充，并有有限的超时和年龄控制。这个锁不是 TTL，缩短新鲜度寿命也不会隐式开启锁。新鲜条目复用与并发未命中合并，需要通过不同对照才能验证。

快速验证

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

将脚本保存为 check-microcache.py，准备 Python、Docker 和固定镜像后执行。记录环境为 Linux arm64 上的 nginx 1.28.0。可丢弃后端报告每条路径的请求计数，nginx 使用两秒有效期，并显式设置 Cookie 与 Authorization 绕过条件。监听仅发布到宿主回环，使用的会话和授权值都是公开测试标记，不连接真实账户：

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'
from concurrent.futures import ThreadPoolExecutor
import threading
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
from urllib.parse import urlsplit,parse_qs
import json,threading
lock=threading.Lock();counts={};gates={'/lock':threading.Event(),'/nolock':threading.Event()}
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 parsed=urlsplit(self.path)
 if parsed.path=='/control/state':
 with lock:data=dict(counts)
 elif parsed.path=='/control/release':
 gates[parse_qs(parsed.query)['path'][0]].set();data={'released':True}
 else:
 with lock:counts[self.path]=counts.get(self.path,0)+1;count=counts[self.path]
 if parsed.path in gates:assert gates[parsed.path].wait(15)
 data={'path':self.path,'count':count,'cookie':self.headers.get('Cookie'),'authorization_present':bool(self.headers.get('Authorization'))}
 body=json.dumps(data,sort_keys=True).encode();self.send_response(200)
 if parsed.path=='/cookie':self.send_header('Set-Cookie','fixture=public-example; Path=/')
 if parsed.path=='/private':self.send_header('Cache-Control','private')
 if parsed.path=='/no-store':self.send_header('Cache-Control','no-store')
 self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
extra='''
proxy_cache_path /tmp/cache levels=1:2 keys_zone=pages:1m inactive=30s max_size=10m;
map $http_cookie $skip_cookie { default 1; "" 0; }
map $http_authorization $skip_auth { default 1; "" 0; }
proxy_cache pages; proxy_cache_key "$scheme|$proxy_host|$request_uri"; proxy_cache_valid 200 2s;
proxy_cache_bypass $skip_cookie $skip_auth; proxy_no_cache $skip_cookie $skip_auth;
proxy_cache_lock on; proxy_cache_lock_timeout 5s; proxy_cache_lock_age 5s;
add_header X-Cache $upstream_cache_status always;
'''
locations='''
location /control/ { proxy_cache off; proxy_pass http://backend:8081; }
location = /nolock { proxy_cache_lock off; proxy_pass http://backend:8081; }
location / { proxy_pass http://backend:8081; }
'''
with lab(config(locations,extra),backend=backend) as (_,request):
 def get(path,headers=None):
 status,h,b=request(path,headers=headers);assert status==200;return h.get('x-cache'),json.loads(b)
 results={}
 first=get('/item?x=1');second=get('/item?x=1');assert first[0]=='MISS' and second==('HIT',first[1])
 other=get('/item?x=2');assert other[0]=='MISS' and other[1]['path']!=first[1]['path']
 results['fresh']=[first[0],second[0]];results['different_query']=other[0]
 for name,headers in [('cookie',{'Cookie':'session=public-fixture'}),('authorization',{'Authorization':'Bearer public-fixture'})]:
 private=get('/item?x=1',headers);assert private[0]=='BYPASS' and private[1]!=first[1]
 assert get('/item?x=1')==('HIT',first[1])
 new='/new-'+name;assert get(new,headers)[0]=='BYPASS'
 public=get(new);assert public[0]=='MISS' and public[1]['cookie'] is None and not public[1]['authorization_present']
 results[name]={'warm_key':'BYPASS','public_after_private_miss':public[0]}
 for path in ['/cookie','private','no-store']:
 path='/'+path.lstrip('/');a=get(path);b=get(path)
 assert a[0]==b[0]=='MISS' and a[1]['count']==1 and b[1]['count']==2
 results[path]=[a[0],b[0]]
 deadline=time.monotonic()+6
 while time.monotonic()<deadline:
 value=get('/item?x=2')
 if value[0]=='EXPIRED':break
 assert value[0]=='HIT';time.sleep(.15)
 else:raise AssertionError('TTL did not expire')
 assert value[1]['count']==2;results['after_ttl']={'status':value[0],'count':value[1]['count']}
 for path,number,origin_count in [('/lock',6,1),('/nolock',4,4)]:
 barrier=threading.Barrier(number+1)
 def client():barrier.wait();return get(path)
 with ThreadPoolExecutor(max_workers=number) as pool:
 futures=[pool.submit(client) for _ in range(number)];barrier.wait()
 wait(lambda:get('/control/state')[1].get(path)==origin_count)
 time.sleep(.3);before=get('/control/state')[1][path]
 assert before==origin_count and not any(f.done() for f in futures)
 get('/control/release?path='+path);responses=[f.result(timeout=10) for f in futures]
 assert get('/control/state')[1][path]==origin_count
 statuses=sorted(r[0] for r in responses)
 if path=='/lock':assert statuses==['HIT']*5+['MISS'] and all(r[1]==responses[0][1] for r in responses)
 else:assert statuses==['MISS']*4
 results[path]={'origin_requests_while_held':before,'cache_statuses':statuses}
 print(json.dumps(results,sort_keys=True))

首次公开请求 /item?x=1 报告 MISS，下一次报告 HIT，并保留相同后端结果。/item?x=2 有自己的 MISS，响应中的路径也不同。持续检查第二个条目，最终观察到 EXPIRED，后端计数变为二。这依据服务器时钟观察实际过期，不假定精确到亚秒的切换时刻；测试关注状态变化及重新计算，而不是某个固定睡眠值。

携带示例会话 Cookie 或授权标记时，即使公开条目已经预热，请求仍报告 BYPASS。之后的公开请求仍返回原公开 HIT。另一个对照先用这些头访问尚未出现的键，再公开访问；公开请求结果是 MISS，证明之前私有上下文的响应没有填充可复用条目。这样同时覆盖了绕过读取和禁止保存，而不只是证明某次私有请求到达后端。

后端带有 Set-Cookie、Cache-Control: private 或 Cache-Control: no-store 的响应，各自连续两次都报告 MISS，源站计数也增加。配置没有忽略这些响应控制。这区分了客户端上下文触发的绕过策略和源站声明的存储限制；不能以缓存只保留几秒为理由，覆盖其中任何一种隐私信号。是否允许共享应先于寿命长短判断。

对于开启锁的冷条目，六个客户端同时开始，后端故意暂不返回响应。放行前后端只看到一次请求；放行后，一个客户端报告 MISS，五个报告 HIT，并得到相同结果。对于另一个关闭锁的条目，四个被保持的客户端产生四次回源，全部报告 MISS。受控放行使重叠的未命中直接可见，而不是从总耗时推测是否发生请求合并。

分别决定新鲜度与过载行为

本实验的两秒设置用于符合条件的 200 响应，相关源站缓存头可以优先于配置有效期。应先决定哪些响应能共享，再选择寿命，并让缓存键对应真正改变内容的输入。高命中率不能证明选中的表示正确；如果键把不同用户或不同内容合并，命中率甚至可能很好，但语义已经错误。验证内容身份和减少回源需要一起进行。

等待锁的请求用额外等待换取较少源站工作。本实验在锁限制内放行后端，并没有证明限制到期或后端失败时仍永远只有一次回源。应结合服务可接受延迟和失败行为，审阅锁等待超时、锁年龄以及可能采用的过期响应策略。是否允许返回过期条目，不能由已经设置短 TTL 这一事实代替决定。

观察缓存状态时，同时核对源站计数和响应身份。MISS 表示请求表示没有作为缓存命中提供，BYPASS 则标明这里显式排除读取的路径。新鲜 HIT、EXPIRED 后重新填充，以及有意提供过期内容，不应混成一个笼统的“已缓存”结果。它们对正确性与后端负载的影响不同，正是需要分别测量和解释的原因。

来源

nginx proxy module，缓存有效期、缓存锁、绕过读取、禁止保存与响应头控制，已核验 2026-10-15。
nginx content caching guide，缓存键、状态观察与缓存行为，已核验 2026-10-15。
RFC 9111 HTTP Caching，新鲜与过期响应，以及 private、no-store 指令，已核验 2026-10-15。

nginx 验证器是否可靠，取决于表示身份是否准确

Thu, 17 Feb 2028 00:00:00 +0000

验证器让接收方询问：自己保存的表示，是否仍与当前选中的表示相符。条件 GET 验证成功时，可以返回没有正文的 304，避免重新传输内容。新鲜度是另一个决定，它控制已存响应何时能直接复用而不发送这次请求。ETag 本身不指定缓存寿命，304 也不是一份替代正文；客户端需要保留原响应，才能利用成功验证的结果。

坏掉的样子

把所有 ETag 都叫作正文哈希，会掩盖 nginx 的一个重要实现细节。在这里测试的 1.28.0 静态文件实现中，生成的标签组合了修改时间和内容长度，并不计算文件内容哈希。如果替换字节时保留这两个输入，就可能保留同一个标签。于是，持有不同旧字节的客户端仍收到看似成功的验证，错误不能仅靠“响应里有 ETag”来排除。

强弱验证器适用于不同比较。对于需要字节身份的用途，强验证器必须能区分表示数据变化；弱验证器则可以把字节不同、但被认为语义等价的表示归在一起。W/ 并不是“接受字节等价变化”的标志，也不意味着这个标签适用于所有前提条件或字节范围续传。使用哪种比较，需要依据具体请求条件，而不是凭标签外观猜测。

条件请求不保证省掉应用计算。服务器可能先生成表示，之后才判断验证器是否匹配。这个静态 nginx 示例根本没有应用渲染器。较小的响应在这里证明节省了正文传输，却不能证明数据库查询、渲染成本或回源请求数必然减少。评估优化效果时，应把实际减少的数据传输和实际减少的后台工作分别测量。

快速验证

把脚本保存为 check-validators.py，先取得固定摘要的 nginx 镜像，再用 Python 和 Docker 运行。它通过宿主回环提供一个可丢弃的四字节静态文件，实测 nginx 版本为 1.28.0。实验只控制容器内文件的时间属性，不修改宿主时间，也不修改共享 Docker 虚拟机时钟：

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'
files={'asset.txt':'AAAA','noetag.txt':'AAAA'}
with lab(config('location = /noetag.txt { etag off; }'),files) as (proxy,request):
 def timestamp(value):docker('exec',proxy,'touch','-m','-d','@'+str(value),'/srv/asset.txt')
 timestamp(1577836800)
 status,headers,body=request('/asset.txt');assert status==200 and body==b'AAAA'
 tag=headers['etag'];modified=headers['last-modified'];results={'etag':tag,'last_modified':modified}
 cases={
 'matching_tag':({'If-None-Match':tag},304),
 'weak_comparison':({'If-None-Match':'W/'+tag},304),
 'matching_date':({'If-Modified-Since':modified},304),
 'tag_takes_precedence':({'If-None-Match':'"different"','If-Modified-Since':modified},200),
 'weak_if_match_rejected':({'If-Match':'W/'+tag},412),
 }
 for name,(conditions,expected) in cases.items():
 status,_,body=request('/asset.txt',headers=conditions);assert status==expected,(name,status)
 if status==304:assert body==b''
 results[name]=status
 docker('exec',proxy,'sh','-c','printf BBBB > /srv/asset.txt');timestamp(1577836800)
 status,current,body=request('/asset.txt');assert status==200 and body==b'BBBB' and current['etag']==tag
 status,_,body=request('/asset.txt',headers={'If-None-Match':tag});assert status==304 and body==b''
 results['changed_bytes_preserved_metadata']=status
 timestamp(1577836802)
 status,current,body=request('/asset.txt',headers={'If-None-Match':tag})
 assert status==200 and body==b'BBBB' and current['etag']!=tag and current['last-modified']!=modified
 results['changed_metadata']={'status':status,'etag':current['etag']}
 status,current,_=request('/noetag.txt');assert status==200 and 'etag' not in current
 print(json.dumps(results,sort_keys=True))

最初文件内容是 AAAA，修改时间固定为 2020-01-01，产生 ETag "5e0be100-4"。GET 在 If-None-Match 中携带这个标签时，得到正文为空的 304。把请求标签加上 W/ 仍返回 304，因为该条件采用弱比较。在本次配置中，携带相等 If-Modified-Since 日期，也会得到 304。这些结果展示标签与日期两条验证路径。

如果同时发送不匹配的 If-None-Match 和匹配日期，则返回 200。实体标签条件优先于日期条件；不能通过补一个有利时间戳，让不匹配标签被忽略。单独的 If-Match 检查会拒绝弱请求标签并返回 412。这里实际执行的是 GET 前提条件检查，并没有执行写入业务流程，因此不能把结果扩展为完整并发写保护已经验证。

随后脚本把 AAAA 改成 BBBB，并恢复原修改时间。无条件 GET 证明正文已经变化，而标签仍完全相同。再次发送旧标签，又得到 304。这是有意构造的反例：即使 nginx 正确执行自己的标签生成算法，部署时保留元数据也可能破坏期望的表示身份契约。检查正文变化和标签变化必须配对进行，不能只看一个成功状态码。

把文件时间推进两秒后，生成的标签和 Last-Modified 都变化了。携带旧标签的请求随后得到 200 和 BBBB。最后一个对照在另一资源上关闭 etag，确认不再生成 ETag 响应头。关闭标签只是移除这一验证器，不会自动得到更强的替代，也不会自动关闭所有缓存。要采取哪种验证策略，仍需与实际发布方式一起设计。

让部署保持验证器契约

如果需要不同版本的字节分别拥有稳定地址，可以用内容导出的文件名在 URL 层区分版本。对于必须保留的稳定 URL，应确保表示字节变化时部署元数据也随之变化，或者由服务应用明确提供合适的内容派生验证器。审阅时既要考虑快速发生的同长度更新，也要检查复制新内容时保留时间戳的工具，避免只覆盖普通手工修改路径。

Last-Modified 同样需要谨慎理解。它是精度有限的时间戳，不是密码学身份。不能把任何日期都直接视为续传所需的强验证器；协议规定的条件和服务器真实更新行为都有关，尤其是一个有效时间精度窗口内可能出现多个版本时。实验推进两秒是为了明确改变输入，并不是宣称等待两秒能解决所有发布一致性问题。

最后，应检查经过中间层和内容编码后真正交付的表示。在要求强比较的场景，一种表示的验证器不能错误地标识另一串不同字节。把缓存寿命、条件验证、隐私和字节完整性分别作为明确决策，并在部署检查中同时验证未变化和已变化两种情况，才能发现这类只在更新时出现的问题。

来源

RFC 9110 HTTP Semantics，强弱验证器、条件优先级及 304、412 响应，已核验 2026-09-12。
RFC 9111 HTTP Caching，新鲜度、已存响应与成功验证，已核验 2026-09-12。
nginx 1.28.0 core source，根据修改时间与内容长度生成静态 ETag 的实现，已核验 2026-09-12。
nginx HTTP core module，etag 与 if_modified_since 配置，已核验 2026-09-12。

HTTP3 走 UDP，HTTP2 仍走 TCP 兜底

Sat, 12 Feb 2028 00:00:00 +0000

HTTP/3 把 QUIC 跑在 UDP:443 上，值得在意的理由是丢一个包的代价。TCP 连接上所有流共用一个字节流，丢一个段就会挡住它后面所有数据的交付，直到重传到达。QUIC 让每条流各自拥有丢失恢复，同一个丢包只挡住数据真的在那个包里的流。

别扭的地方在于这不是一个开关。客户端必须先知道服务器会说 HTTP/3 才可能去试，而它得知这件事所走的那条路径，恰恰是你想优化的那条。

两种传输，一个端口号

UDP:443 和 TCP:443 属于彼此独立的命名空间，所以一个监听可以同时占住两者。这就是为什么 nginx 的 server 块可以把 listen 443 quic reuseport; 和 listen 443 ssl; http2 on; 并排放着，用同一个端口号同时服务 QUIC 和 HTTP/2。reuseport 比看起来更重要：没有它，第二次绑定 UDP:443 会拿到 EADDRINUSE，而这正是两个 server 块都声称要占用 QUIC 监听时看到的报错。

QUIC 不是「HTTP/2 搬到 UDP 上」。它把传输握手和 TLS 握手合成一趟——一个往返，复用会话时是零个——并且携带一个与地址和端口无关的连接 ID。这个 ID 让连接迁移成为可能，同时也让那些假定一条流永远待在一个五元组上的负载均衡器当场失效。还要记住 QUIC 要求整条路径都能过 UDP：企业网络、机场 Wi-Fi 和部分移动运营商至今仍在整段丢弃 443 端口的 UDP，这正是兜底路径必须一直可用的原因。

Alt-Svc 是客户端得知的方式

对某个源的第一次连接永远是走 TCP 的 HTTP/2，因为客户端此时一无所知。响应里带着一条通告：Alt-Svc: h3=":443"; ma=86400。解析开来就是协议 h3、authority :443、新鲜期 86400 秒，也就是 24 小时。下一次连接该源时客户端会先试 QUIC，所以升级发生在后续某次访问，永远不会发生在第一次。

ma 才是咬人的地方。只要通告还在新鲜期内，客户端每建立一条新连接都会先试 HTTP/3——哪怕 HTTP/3 已经反复失败。把 UDP:443 被中间盒静默丢弃的情形建个模型：客户端在 QUIC 探测超时退避里烧掉 15 秒（1、2、4 再到 8 秒）才回退到 HTTP/2。按每天 20 次访问算，就是每天白白丢掉 300 秒，一直持续到一天后缓存过期。反过来，不等 QUIC 放弃就并行发起 TCP 连接，同一条被阻断的路径 0.1 秒就能出结果。回退的代价是设计选择，不是协议开销。

0-RTT 与连接迁移是两处锋利的边缘

0-RTT 允许回访客户端在第一个飞行包里就发出应用数据，用的是上一会话留下的票据。这些数据可以被重放——抓到那个飞行包的人可以再发一次——所以只有可以安全重复的请求才该放进去。把「创建订单」放在 0-RTT 里，等于预订了一笔重复订单。

连接迁移是另一处。QUIC 用连接 ID 而不是地址来标识连接，所以从 Wi-Fi 漫游到蜂窝网的客户端能保住同一条连接。把一台按五元组做哈希的负载均衡器放在前面，这条继续存在的连接就会落到另一个后端：八个后端的情况下，把同一客户端漫游前后的键算出来，先落到 7 号，再落到 4 号。协议的移动性变成了负载均衡器的问题。

坏掉的样子

第一种失败，是客户端缓存着 Alt-Svc，而网络把 UDP 丢了。它的表象是整整一天里每次导航首字节都很慢，而服务器日志里没有任何异常——QUIC 的 Initial 根本没到，也就没有东西可记。把服务端的 HTTP/3 连接数和客户端感知到的延迟放在一起比；h2 路径健康却出现巨大落差，就是它的特征。缓解办法是缩短 ma、并行竞速 TCP 连接，以及不要在你验证不了的路径上通告 h3。

第二种失败，是连接迁移打坏了会话亲和性。移动客户端在会话中途换地址，HTTP/3 把连接保住了，而此刻接管它的后端没有任何原先那台持有的缓存或会话状态。它的表象是间歇性的认证失败、缓存不命中、上传做了一半，而且只出现在移动端客户端上——这也是它难以复现的原因。按连接 ID 路由，或者把亲和性钉在一个能扛住地址变化的东西上。

快速验证

确认两条路径都真的活着：

curl -sI https://example.com/ | grep -i alt-svc
curl -s --http3-only -o /dev/null -w '%{http_version} %{time_appconnect}\n' https://example.com/
nginx -T 2>/dev/null | grep -nE 'listen .*quic|http3|Alt-Svc'
ss -lun | grep -E ':443\b'

第一条应当打出一条带有限 ma 的 h3 通告。第二条在 UDP 通的时候打出 3 和很小的连接耗时，路径被挡时则直接失败——第一条成功而这里失败，就是典型的中间盒情形。第三条看配置是否真把 QUIC 和响应头接在了一起，第四条证明 443 上确实有一个 UDP 套接字被绑定。

来源

RFC 9114 HTTP/3，HTTP/3 在 QUIC 之上的语义，已核验 2026-09-16。
RFC 7838 HTTP 替代服务，Alt-Svc 头及其新鲜期，已核验 2026-09-16。
ngx_http_v3 模块，nginx 的 QUIC 与 HTTP/3 指令，已核验 2026-09-16。
RFC 9000 QUIC，流级丢失恢复、连接 ID 与 0-RTT，已核验 2026-09-16。

SNI 让一个 IP 承载多个 HTTPS 站点

Mon, 07 Feb 2028 00:00:00 +0000

Server Name Indication（简称 SNI）在 TLS 握手中把目标主机名发给服务器，于是同一个 IP 地址能同时承载多张证书、多个站点。在它之前算法很残酷：一张证书占一个地址，一个站点占一个地址，地址像水一样花出去。基于名字的虚拟主机对明文超文本管用，对加密流量却不行——服务器必须在加密请求暴露目标站点之前先选好证书。SNI 把悖论解开了：主机名提前一步，进握手本身，跑在加密前面。

现实成果就是今天的共享边缘：内容分发、平台路由、单机多租户，全靠它把几千张证书复用到几个地址上。但机制有三处利齿值得认识——隐私外泄、老客户端、缺省证书陷阱——每一处都在新租户上线或老客户端投诉时准时咬人。

名字最先报出

在交换密钥之前，客户端就在握手里发出想要的主机名，服务器据此选对虚拟主机和证书。因为名字先于加密到达，nginx 才能在一条连接里同时完成路由与选证书。扩展住在第一条握手报文里，不多花一次往返——选证书和本来就要做的握手在同一趟车里完成。

这个顺序也解释了它为什么不能只靠服务端单方面升级。客户端必须发这个扩展；没学过的客户端拿到缺省证书，拿它去校验自己想要的名字。老旧嵌入库、十年前的支付终端、工业控制器，真实机群里至今还有不带它的——认定全员支持之前，先看清自己的客户端构成。

用 server_name 匹配

主机名是路由元数据，而不是秘密：它以明文往返，负载均衡器或中间设备都能读到。nginx 拿它去和 server_name 匹配，决定走哪个 server 块、用哪张证书。每个站点块自带证书与私钥，共享一个监听套接字的各块按规则比对：精确名先行，再通配头尾，最后正则，和超文本主机头的匹配同一套路。

证书选对还不等于请求一定到对的应用。客户端会先验证证书的 SAN 是否覆盖它发送的名字，握手成功后才发送加密的 HTTP Host；反向代理若在第二层使用了另一套名字，证书看似正确，响应仍可能来自错误租户。把每个租户的 SNI 名、证书 SAN、server_name 和上游路由放在同一份清单里，新增或续期时逐项核对。SNI 解决的是证书选择，不是主机名保密，也不是应用授权。

传输层的站点表和应用层的主机预期必须一致，否则重定向和规范化会和证书打架。典型错配是证书对了、应用错了：握手命中甲块，主机头却进了乙块的逻辑，吐出签名正确、内容错误的响应。两边名字照镜子，两层都测，有分歧就当缺陷修，别当灵活用。

把缺省回退控制好

当虚拟主机一个都没命中时，nginx 会抛出第一个配置的证书作为缺省。因此 listen 443 ssl 块的顺序决定未知名字回退到哪个站点，别人直接敲 IP 也会命中这块。缺省块要招待三种客人：扫地址的扫描器、不带扩展的老客户端、域名过期或打错字误指过来的名字。每种都值得一个刻意的回答——中性落地页、直接断开、静默丢弃——而不是谁先配置谁待客。

用缺省标记把意图写死，挪文件顺序也改不了行为。还要监控缺省块在伺候谁：它的流量突然上涨，往往是别处域名配错、证书过期或有人在扫的早期信号。回退块既是安全网也是传感器，它的请求速率单独成图，别和租户的混在一起。

坏掉的样子

经典故障是加租户后的证书告警：新站点块写了，证书文件也合法，客户端却看到旧缺省。按概率排序：块加进了主配置从没加载的文件（缺引用或重载失败）、站点名拼写错到肉眼跳过、两个块抢同一个名字先到先得。诊断看有效配置转储——读服务器眼里的世界，别读文件暗示的世界——再用带名字指示的握手工具逐个名字看实际下发的是哪张证书。

第二种故障是没人计划的隐私外泄：主机名明文走全程，客户端与服务器之间的每个中间盒、每个被动观察者都看得见。对敏感租户，这等于在证书全合法的情况下泄露了浏览意图。Encrypted Client Hello 是正在路上的答案，但部署还零零散散——对威胁模型包含网络观察者的租户如实告知，而不是许诺这一层本来就给不了的保密。

快速验证

逐名验证证书与回退：

nginx -T 2>&1 | grep -B2 -A4 'server_name\|ssl_certificate ' | head -n 40
openssl s_client -connect 203.0.113.10:443 -servername shop.example.com </dev/null 2>/dev/null | openssl x509 -noout -subject -issuer
openssl s_client -connect 203.0.113.10:443 -servername unknown.invalid </dev/null 2>/dev/null | openssl x509 -noout -subject

每个名字必须拿到自己的证书，未知名字必须拿到刻意的缺省。

来源

TLS SNI 概览，解释 SNI 用途与隐私权衡，已核验 2026-06-01。
nginx HTTPS 服务配置，HTTPS 服务配置官方指南，已核验 2026-09-05。

gzip、HTTP/2 与 Brotli 需要分别验证

Fri, 28 Jan 2028 00:00:00 +0000

HTTP/2 改变 HTTP 传输分帧和多路复用方式；gzip 与 Brotli 编码的是表示数据。启用 HTTP/2 不会自动压缩响应正文，启用 gzip 也不能证明客户端协商出了 HTTP/2。HTTP/2 的头部压缩又是另一种机制。可靠检查应分别记录协商协议、响应 Content-Encoding、传输正文字节数，以及实际解码后得到的内容，不能用其中一项代替其他结果。

坏掉的样子

发送 Accept-Encoding: gzip, br，然后把结果保存成 .br，并不能证明使用了 Brotli。服务器可能选择 gzip，也可能发送仍被请求接受的原始表示。真实编码由响应头说明。根据请求列表或输出文件名猜测，会导致使用错误解码器，也可能让报告声称获得了实际上根本没有发生的压缩结果。文件名只是本地命名，不是协议证据。

Brotli 支持还属于部署能力，并不是安装 nginx 后自然具备的功能。Brotli 过滤和预压缩文件处理由独立模块提供，需要针对实际二进制与配置确认可用性、构建兼容性。添加不受支持的指令可能让配置验证失败，而客户端声明接受 Brotli 不会替服务器安装功能。检查模块时，应以当前程序行为为准，不能从另一台机器的配置推断。

客户端自动解码会制造另一种测量陷阱。curl --compressed 收到较小编码正文后，可以保存成较大的解码文件。把这个文件大小与原始压缩输出比较，实际比较的是不同对象。反过来，只使用 --http2 却不检查协商结果，也可能把允许的协议回落误当成 HTTP/2 已经成功验证。命令选项表达请求意图，结果字段才说明本次发生了什么。

快速验证

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

将脚本保存为 check-h2-coding.py，准备 Docker、Python、OpenSSL 和支持 HTTP/2 的 curl 后运行。记录客户端为带 nghttp2 的 curl 8.7.1，服务器为 Linux arm64 上的 nginx 1.28.0。脚本生成短期本地证书，并通过 --cacert 显式信任该证书，只发布宿主回环端口，不需要连接真实公网服务：

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 gzip,hashlib
payload=(b'{"message":"'+b'HTTP content coding and transport are separate. '*1000+b'"}\n')
with TemporaryDirectory(prefix='xbcatm-local-tls-') as directory:
 root=Path(directory);cert=root/'cert.pem';key=root/'key.pem'
 result=subprocess.run(['openssl','req','-x509','-newkey','ec','-pkeyopt','ec_paramgen_curve:prime256v1',
 '-nodes','-keyout',str(key),'-out',str(cert),'-days','1','-subj','/CN=localhost',
 '-addext','subjectAltName=DNS:localhost,IP:127.0.0.1'],capture_output=True,text=True)
 assert result.returncode==0,result.stderr
 configuration=config('location = /app.json {} location / { return 404; }',
 'gzip on; gzip_types application/json; gzip_vary on; types { application/json json; }')
 configuration=configuration.replace('listen 8080;', 'listen 8080 ssl; http2 on; ssl_certificate /srv/cert.pem; ssl_certificate_key /srv/key.pem;')
 files={'cert.pem':cert.read_bytes(),'key.pem':key.read_bytes(),'app.json':payload,
 'brotli.conf':'events {} http { brotli on; server { listen 8080; } }'}
 with lab(configuration,files) as (proxy,request):
 probe=docker('exec',proxy,'nginx','-t','-c','/srv/brotli.conf',check=False)
 assert probe.returncode!=0 and 'unknown directive "brotli"' in probe.stderr
 results={'brotli_directive_supported':False}
 for name,version,accept,decode in [
 ('h2_gzip','2','gzip, br',False),('h1_gzip','1.1','gzip',False),
 ('h2_br_only','2','br',False),('h2_identity','2','identity',False),
 ('h2_decoded','2','gzip',True)]:
 output=root/(name+'.body');header=root/(name+'.headers')
 args=['curl','--silent','--show-error','--fail','--noproxy','*','--cacert',str(cert),
 '--http2' if version=='2' else '--http1.1','--header','Accept-Encoding: '+accept,
 '--output',str(output),'--dump-header',str(header),'--write-out','%{http_version}\n%{size_download}\n',
 f'https://127.0.0.1:{request.port}/app.json']
 if decode:args.insert(1,'--compressed')
 run=subprocess.run(args,capture_output=True,text=True,timeout=15);assert run.returncode==0,run.stderr
 actual,download=run.stdout.strip().splitlines();assert actual==version,(name,run.stdout)
 headers={k.lower():v.strip() for line in header.read_text().splitlines() if ':' in line for k,v in [line.split(':',1)]}
 body=output.read_bytes();encoded='gzip' in accept
 assert headers.get('content-encoding')==('gzip' if encoded else None)
 assert (gzip.decompress(body) if encoded and not decode else body)==payload
 assert headers['vary']=='Accept-Encoding'
 results[name]={'protocol':actual,'content_encoding':headers.get('content-encoding','identity'),
 'download_body_bytes':int(download),'saved_file_bytes':len(body)}
 assert results['h2_gzip']['download_body_bytes']<len(payload)
 assert results['h2_decoded']['saved_file_bytes']==len(payload)
 rejected={}
 for path in ['/key.pem','/cert.pem','/brotli.conf']:
 run=subprocess.run(['curl','--silent','--show-error','--noproxy','*','--cacert',str(cert),
 '--http2','--output',str(root/'rejected.body'),'--write-out','%{http_code}',
 f'https://127.0.0.1:{request.port}'+path],capture_output=True,text=True,timeout=15)
 assert run.returncode==0 and run.stdout=='404',(path,run.stdout,run.stderr)
 rejected[path]=404
 results['non_asset_statuses']=rejected
 results['original_sha256']=hashlib.sha256(payload).hexdigest()
 print(json.dumps(results,sort_keys=True))

证书的主题备用名称包含回环 IP，因此本地 HTTPS 请求可以同时验证信任和请求身份。实验没有关闭证书校验。路由只允许提供 JSON 资源，请求密钥、证书和探测配置都必须返回 404。临时密钥只存在于可丢弃测试文件和镜像中，不输出密钥内容；结束时清理自己的容器、镜像标签、网络和临时文件。这些设置用于建立可验证的本地 TLS 条件，不代表替生产域名完成了证书部署。

合成 JSON 表示共有 48,015 字节。在实际协商出的 HTTP/2 上，请求同时声明 gzip 和 Brotli，收到 Content-Encoding: gzip，记录到正文为 381 字节。解码能逐字节还原原内容。显式使用 HTTP/1.1 时也得到 gzip。两组结果说明正文编码可以跨这两种已测传输使用，而不是只有选中 HTTP/2 才会发生压缩。

HTTP/2 的 identity 请求得到 48,015 字节未编码正文。只声明 br 的请求在此配置中也得到 identity，因为该请求头仍接受原始表示。实验另外用包含 brotli on 的配置执行检查，并要求 nginx 以未知指令拒绝它。这两个观察共同说明：本次被测配置没有交付 Brotli，不能把客户端声明和服务器实际能力混为一谈。

使用 --compressed 时，curl 仍报告下载正文为 381 字节，但保存文件包含原来的 48,015 字节解码内容。脚本同时核对两种计量和实际内容。下载正文数字不包含其他传输开销，它不是完整抓包，也不是该连接所有 TLS 与 HTTP/2 分帧字节的总量。比较压缩收益时，应让计量边界保持一致。

先确认能力，再比较性能

示例在 TLS 监听上显式开启 HTTP/2，并检查 curl 返回的真实协议值。它在本地提供静态内容，因此不对上游应用采用什么传输协议作结论。反向代理可以与客户端协商一种协议，又用另一种协议连接后端；如果这个区别影响容量或行为，应分别检查两条连接，不能把入口协议直接推广到整个调用链。

部署 Brotli 时，先建立实际模块或预压缩文件交付路径，再要求得到真实 br 响应并成功 Brotli 解码，之后才讨论节省量。这里提供的是负向能力检查，不是 Brotli 性能基准。安装模块或重新构建 nginx 属于另一项配置变更，需要针对兼容性和实际交付重新验证，而不是把未经执行的安装步骤写成已有结果。

最后，要用有代表性的内容和一致计量比较效果。高度重复的测试正文证明编码与解码正确，不提供通用压缩比，也不证明页面一定加速多少。通过 Vary 表达的缓存选择、编码正文字节、解码正确性、CPU 使用和客户端延迟，应作为不同观察记录。协议版本或编码器名称本身，都不足以证明页面变快。

来源

nginx gzip module，响应内容编码及 Vary 配置，已核验 2026-10-15。
nginx HTTP/2 module，HTTP/2 启用与 TLS ALPN 要求，已核验 2026-10-15。
Google ngx_brotli module README，独立 Brotli filter、static 模块及构建要求，已核验 2026-10-15。
RFC 9110 HTTP Semantics，内容编码协商及 identity 的可接受性，已核验 2026-10-15。

先决定让 nginx 跳转客户端，还是在内部重写

Fri, 21 Jan 2028 00:00:00 +0000

nginx 跳转与内部重写改变请求流程的不同部分。跳转返回状态和 Location，由客户端决定是否发起新请求；内部重写则在处理现有请求时改变 nginx 当前 URI。两者的选择决定客户端是否看到新地址、location 是否重新搜索，以及最终处理器收到怎样的路径和查询。不能因为都能让某个 URL 得到内容，就把它们当成同一种操作。

坏掉的样子

本来需要内部映射，却改成跳转，会增加客户端往返并暴露新 URL；本来需要公开永久迁移，却只做内部重写，客户端仍会继续使用旧地址。return 和 rewrite 也不能被当成总是默认相同跳转行为的通用缩写。明确状态码与重写标志，才能让预期转换可审阅，避免一行看似简单的配置隐藏行为差异。

状态选择影响方法语义和缓存。307、308 在自动跳转时保留请求方法，301、302 则允许历史上的 POST 改为 GET。永久不意味着每个客户端立刻更新所有已保存链接，临时也不意味着响应绝对不能缓存。缓存指令、请求上下文和客户端行为仍然重要，不能用状态名称替代明确的复用策略。

内部重写还可能选择错误处理器，或反复匹配自己。last 会为改变后的 URI 开始新 location 搜索；break 结束当前重写序列后，继续在现有 location 处理。查询参数可以按替换语法追加或丢弃。把这些区别视为可以互换，可能导致读取错误文件、重复参数，或进入返回 HTTP 500 的循环。

快速验证

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

使用宿主 Python、Docker 和固定 nginx 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Docker 29.3.1。它构建并检查可丢弃配置，只发布回环端口，不自动跟随跳转地验证真实响应，最后清理自身资源。一个小型静态文件让 break 所用处理器可以与目标 location 清楚区分：

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_text(content)
 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()
 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'

locations=r'''
location = /old { return 308 /destination$is_args$args; }
location = /destination { return 200 "$request_method|$uri|$args"; }
location /last/ { rewrite ^/last/(.*)$ /target/$1 last; }
location /break/ { rewrite ^/break/(.*)$ /target/$1 break; add_header X-Route break always; }
location /target/ { add_header X-Route target always; return 200 "$uri|$args"; }
location /append/ { rewrite ^/append/(.*)$ /target/$1?new=1 last; }
location /discard/ { rewrite ^/discard/(.*)$ /target/$1? last; }
location /loop/ { rewrite ^ /loop/again last; }
'''
with lab(config(locations,'absolute_redirect off;'),{'target/item':'static-file'}) as (container,request):
 status,headers,body=request('/old?x=1',method='POST',body='public-body')
 assert status==308 and headers['location']=='/destination?x=1'
 status,headers,body=request(headers['location'],method='POST',body='public-body');assert status==200 and body==b'POST|/destination|x=1'
 status,headers,body=request('/last/item?x=1');assert status==200 and headers['x-route']=='target' and body==b'/target/item|x=1'
 status,headers,body=request('/break/item?x=1');assert status==200 and headers['x-route']=='break' and body==b'static-file'
 status,headers,body=request('/append/item?old=2');assert status==200 and body==b'/target/item|new=1&old=2'
 status,headers,body=request('/discard/item?old=2');assert status==200 and body==b'/target/item|'
 assert request('/loop/start')[0]==500
 assert 'rewrite or internal redirection cycle' in docker('exec',container,'cat','/tmp/error.log').stdout
 print('return 308 creates a client-visible redirect; the explicit follow-up retains POST and the query')
 print('last restarts location selection; break keeps the location while changing the URI used by its static handler')
 print('rewrite appends old query arguments unless discarded explicitly; an internal rewrite cycle is stopped with HTTP 500')

向 /old?x=1 发送 POST，得到 308 和 Location: /destination?x=1。实验关闭绝对跳转生成，让本地目标保持相对形式，不依赖自动分配的宿主端口。任何后续请求之前，都会先检查原响应，从而明确 nginx 实际告诉客户端什么，不让自动跟随把第一跳隐藏起来。

随后，脚本显式向该 Location 再发送一次 POST，得到 POST|/destination|x=1。这验证按预期方法跟随时的目标和查询，但不声称覆盖所有浏览器的自动跳转或缓存行为。测试客户端有意控制第二次请求，而不是默默执行它。因此，实验结果应与 HTTP 状态契约结合理解，不能扩展成未经执行的客户端兼容性结论。

/last/item?x=1 被重写为 /target/item，并重新选择 location。目标块返回诊断 URI，X-Route 为 target。相比之下，/break/item?x=1 改变 URI 后仍留在原 location，其静态处理器读取 /srv/target/item，响应标记为 break。相同目标路径因此可以经过不同配置处理，不能只看重写后的字符串。

这些结果说明 break 不会停止全部请求处理，它只停止当前重写序列，内容处理仍继续。同样，last 不是外部跳转：客户端直接收到最终 200，不会先获得一条 Location 跳到内部目标。状态、响应头与正文共同证明转换类型，避免仅凭规则名字猜测。

/append/item?old=2 的替换包含 new=1，它与原参数组合成 new=1&old=2。丢弃示例在替换末尾使用问号，最终没有参数。两种情况都断言实际结果，避免跳转或重写测试漏掉重复、泄漏或意外删除的查询数据。路径正确不代表参数同样正确，两者应分别比较。

循环路径不断重写回自身匹配家族。nginx 最终以 HTTP 500 停止循环，并在错误日志记录内部跳转循环诊断。因此，语法检查成功不证明某个请求不会循环；只有实际执行相关匹配路径，才能验证转换按预期终止。错误日志还为区分后端故障与本地规则循环提供了直接证据。

测试客户端真正收到的转换

简单公开迁移可以使用带明确状态的 return，需要模式匹配时再采用对应 rewrite。目标路径和查询处理应清楚表达。避免让不可信输入任意决定跳转地址；绝对目标依赖传入主机信息时，还要验证规范主机策略。配置不应因为修复一个路径，顺便允许请求者选择完全无关的目标。

公开迁移在选择缓存策略前，应验证状态、Location、方法预期和最终目标。需要禁止复用时，临时状态不能替代明确缓存控制。内部映射则应检查最终 location、文件或上游路径、参数及错误情况。两类验证关注不同结果，不应把其中一种成功直接代替另一种。

回归应包含近似路径和已经规范化的目标。规则第一次工作，不代表不会再次跳转自己的目标，或与后续 location 冲突。保留原始响应和最终结果两侧证据，才能在部署后解释路由改变到底发生在哪一步，而不是只看到页面最终能打开就结束检查。

来源

nginx rewrite module，return 跳转、last 与 break、查询处理及重写次数限制，已核验 2026-10-15。
RFC 9110 HTTP semantics，跳转状态含义与方法保留要求，已核验 2026-10-15。
RFC 9111 HTTP caching，响应语义及缓存控制共同决定的缓存行为，已核验 2026-10-15。

nginx 前缀在匹配结束前只是候选配置

Mon, 17 Jan 2028 00:00:00 +0000

nginx location 在已选中的 server 内为请求选择配置。对于这里验证的平面前缀与正则结构，精确匹配会结束搜索；否则 nginx 先记住最长匹配前缀，再可能选择第一个匹配的正则。如果没有适用正则胜出，就使用先前记住的前缀。这是一个完整选择过程，不是简单执行配置文件里最先遇到的块，也不是只比较路径看起来有多具体。

坏掉的样子

前缀是字符串前缀，不会自动要求完整路径段。location /api 也能匹配 /apix。如果真正需要的是端点 /api 和 /api/ 下的后代，应明确表达这两个边界。依赖未声明的路径段边界，可能让只是共享开头字母的路径，进入错误处理器、缓存策略或访问规则。配置应反映真实 URL 集合，而不是依靠读者自行补充含义。

最长普通前缀不一定是最终选择。匹配 .php 的正则，可以接管一个也匹配了更详细 API 前缀的请求。把前缀移到正则之前，不会改变基本优先规则。竞争正则之间的声明顺序有意义，普通前缀则主要比较匹配长度，而不是出现位置。因此，单纯整理文本顺序不一定修复实际路由问题。

^~ 在该前缀成为相关层级的最长匹配前缀时，抑制正则搜索。它不是正则运算符，也不是对所有以某个较短标记前缀开头的路径提供无条件保护。嵌套 location 和内部跳转需要额外推理；下面故意使用平面 server 结构，让每次选择都能明确对应一个规则，不把复杂嵌套情况隐藏在简化结论里。

快速验证

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

先取得固定 nginx 镜像，再用宿主 Python 和 Docker 运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Docker 29.3.1。它构建临时配置镜像，用 nginx -t 验证，再通过只发布到宿主回环的端口发送真实 HTTP 请求，最后清理自己的容器、镜像标签和网络，不改动已有站点配置：

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_text(content)
 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()
 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'

locations=r'''
location / { return 200 "fallback"; }
location /api/ { return 200 "api-slash"; }
location /api/admin/ { return 200 "admin"; }
location = /api { return 200 "exact"; }
location /api { return 200 "api-string"; }
location ^~ /static/ { return 200 "static"; }
location ~ \.php$ { return 200 "php-regex"; }
'''
with lab(config(locations)) as (container,request):
 cases={'/api':'exact','/api?x=1':'exact','/apix':'api-string','/api/users':'api-slash','/api/admin/log':'admin','/api/admin/test.php':'php-regex','/static/test.php':'static','/unmatched':'fallback'}
 for path,expected in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==expected,(path,status,body)
 print('exact matching ignores the query; ordinary prefixes use longest string match, including /api matching /apix')
 print('a regex overrides the ordinary longest prefix, while the selected ^~ prefix skips that regex')

/api 与 /api?x=1 都返回 exact。查询字符串不参与 location 匹配，因此添加参数不会使精确路径停止匹配。所选块显式返回该标记。精确匹配的作用是选择配置，不天然意味着读取某个文件系统根目录，也不会自动决定调用哪个应用；具体处理动作仍由块内配置确定。

/apix 返回 api-string，证明普通 /api 前缀会超出完整 API 路径段。/api/users 返回 api-slash，因为 /api/ 是更长的匹配前缀。/api/admin/log 返回 admin，进一步展示普通最长前缀选择，不需要依赖这些块在文件中的排列顺序。不同标记使每次选择可被直接观察。

/api/admin/test.php 返回 php-regex。较长的 /api/admin/ 曾是候选，但正则阶段选择了另一块。这正是错误假定“前缀更长就一定胜过通用脚本处理器”时会出现的失败方式。如果只检查状态码成功，错误可能完全被掩盖，因此实验让每个处理器返回可区分正文，而不是都返回同一个正常页面。

/static/test.php 返回 static，因为被选中的 /static/ 带有 ^~，同一个后缀正则不会接管请求。不匹配其他规则的路径则返回宽泛的默认标记。这些案例共同验证真实选择边界，而不仅是证明配置语法被 nginx 接受。语法检查和行为检查回答的问题不同，两者都需要保留。

客户端明确发送路径，并同时核对响应正文和状态。实验不包含真实认证策略或脚本执行，所以标记只证明路由选择。将模式用于受保护端点时，还应测试选择之后真正执行的处理器和访问行为。不能因为路由标记正确，就声称认证、授权或后端功能也已经验证。

审阅所选处理器及其后续转换

先明确目标 URL 家族，再列出精确端点、后代前缀和可能重叠的正则。加入 /apix 等近似路径、相关大小写变体，以及编码或规范化形式。nginx 使用规范化 URI 匹配，仅根据原始请求文本做安全审查，可能漏掉最终生效配置。验证用例应来自真实边界，而不是只挑最普通的成功路径。

检查有效配置，包括被包含的文件和实际选中的虚拟服务器。请求没有进入的 server 中，即使某个 location 写得正确，也无法修复另一个 server 的路由。验证时使用受控响应标记或日志，而不是根据多个处理器都可能返回的熟悉页面来猜测选择。诊断证据需要能区分竞争配置。

最后，考虑 rewrite、index 处理和其他可能触发新 location 搜索的内部跳转。首次选中的块不一定是最终处理器。应测试完整请求路径，并保留足够证据解释初次匹配和最终响应，避免把局部正确误认为整个处理链都符合预期。

来源

nginx core location directive，规范化 URI、精确匹配、前缀与正则选择，已核验 2026-10-15。
How nginx processes a request，虚拟服务器选择与 location 请求处理，已核验 2026-10-15。

nginx 突发容量决定哪些请求等待、哪些被拒绝

Wed, 05 Jan 2028 00:00:00 +0000

nginx 请求限流使用漏桶方法，依据配置速率计算超额请求。burst 决定可以接受多少超额，nodelay 和 delay 则影响已经被接受的超额请求何时继续处理。这里涉及准入与调度，并不是所有超过名义速率的请求都会失败，也不是直接测量应用里有多少并发工作。理解这几个不同维度，才能解释一次突发里为何同时出现成功、等待和拒绝。

坏掉的样子

把 nodelay 解释成“立即丢弃超额”，正好说反了它的作用。在突发额度以内，它允许超额请求不经过通常的延迟，直接继续处理；超过额度才拒绝。已经接受的突发仍消耗需要随时间恢复的容量。后端很快完成，并不会让下一批突发自动获得全新额度，因此不能把 nodelay 理解成只管单次批次、不累计速率债务。

被延迟的请求也不会自动变成一串 503。突发范围内获准等待的请求，可以在等待之后得到成功应用响应；超过配置额度才会按所选状态拒绝。客户端自己的截止时间可能在等待中到期，所以服务器能接受的排队，不一定满足客户端延迟契约。讨论结果时应区分服务端拒绝、获准等待和客户端主动超时。

配置语法同样需要验证。在 nginx 1.28.0 中，显式写 burst=0 会被拒绝，尽管省略 burst 的默认超额额度就是零。无效配置不是一种更严格但正常工作的限流策略。应同时做语法检查和真实请求验证，并确认受保护 location 确实进入限流阶段，而不是在更早的 rewrite 阶段通过 return 提前结束。

快速验证

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

将脚本保存为 check-burst.py，准备 Python、Docker 和固定镜像后执行。记录环境使用 nginx 1.28.0 和真实 HTTP 后端。每个案例采用独立的公开测试 key、每秒一个请求的速率，并同时放行六个客户端。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,extra_ports=()):
 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')
 published=[arg for value in (8080,*extra_ports) for arg in ('-p','127.0.0.1::'+str(value))]
 docker('run','-d','--name',containers[0],'--network',name,*published,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;request.network=name
 request.ports={int(key.split('/')[0]):int(value[0]['HostPort']) for key,value in details['NetworkSettings']['Ports'].items() if value}
 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'
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 body=json.dumps({'path':self.path,'method':self.command}).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
from concurrent.futures import ThreadPoolExecutor
import threading
extra='limit_req_zone $arg_k zone=budget:1m rate=1r/s; add_header X-Limit $limit_req_status always;'
locations='location / { return 404; }\n'
for path,policy in [('delay','burst=2'),('nowait','burst=2 nodelay'),('partial','burst=2 delay=1'),('strict','')]:
 locations+=f'location /{path} {{ limit_req zone=budget {policy}; limit_req_status 429; proxy_pass http://backend:8081; }}\n'
locations+='location /default { limit_req zone=budget; proxy_pass http://backend:8081; }'
invalid=config('location / { limit_req zone=b burst=0 nodelay; proxy_pass http://backend:8081; }',
 'limit_req_zone $binary_remote_addr zone=b:1m rate=1r/s;')
with lab(config(locations,extra),{'invalid.conf':invalid},backend) as (proxy,request):
 results={}
 for mode in ['delay','nowait','partial','strict']:
 barrier=threading.Barrier(7)
 def client():
 barrier.wait();start=time.monotonic();status,headers,_=request('/'+mode+'?k='+mode)
 return {'status':status,'limit':headers.get('x-limit'),'elapsed':round(time.monotonic()-start,3)}
 with ThreadPoolExecutor(max_workers=6) as pool:
 futures=[pool.submit(client) for _ in range(6)];barrier.wait();observed=[f.result() for f in futures]
 good=[r for r in observed if r['status']==200];bad=[r for r in observed if r['status']==429]
 assert len(good)==(1 if mode=='strict' else 3) and len(good)+len(bad)==6,observed
 assert all(r['limit']=='REJECTED' for r in bad)
 assert all(r['limit'] in {'PASSED','DELAYED'} for r in good)
 delayed=sum(r['limit']=='DELAYED' for r in good)
 assert delayed=={'delay':2,'nowait':0,'partial':1,'strict':0}[mode],observed
 if mode=='delay':assert sorted(r['elapsed'] for r in good)[-1]>=1.7
 if mode=='partial':assert max(r['elapsed'] for r in good)>=.7
 results[mode]=observed
 if mode=='nowait':
 assert request('/nowait?k=nowait')[0]==429
 time.sleep(1.1);assert request('/nowait?k=nowait')[0]==200
 results['nodelay_debt_then_recovery']=[429,200]
 first=request('/default?k=default');second=request('/default?k=default')
 assert first[0]==200 and second[0]==503 and second[1]['x-limit']=='REJECTED'
 results['default_rejection']=503
 rejected=docker('exec',proxy,'nginx','-t','-c','/srv/invalid.conf',check=False)
 assert rejected.returncode!=0 and 'invalid burst value' in rejected.stderr
 results['literal_burst_zero_valid']=False
 print(json.dumps(results,sort_keys=True))

设置 burst=2 时，一个请求立即通过，另外两个获准超额请求被延迟。记录中的成功响应分别在接近零、一、两秒时完成；其余三个请求返回 429。响应头区分 PASSED、DELAYED 和 REJECTED。这证明获准等待的工作会正常完成，不能把每个延迟请求都描述为最终错误。具体完成时间是本次观察，状态分类才是主要断言。

设置 burst=2 nodelay 时，三个请求成功，而且限流器没有把它们标记为 DELAYED，另外三个返回 429。立即再用同一个 key 请求，也会被拒绝；等待 1.1 秒后，又可以成功。因此实验不仅验证了立即放行突发，还验证了持续存在的速率债务，避免误以为一次快速响应就能让下一批无限重复通过。

设置 burst=2 delay=1 时，两个获准请求无需延迟，第三个延迟约一秒，另外三个被拒绝。省略 burst 时，六个紧密到达的请求只接受一个，其余五个拒绝。测试检查决定类别和较宽的延迟下界，不把毫秒测量写成跨机器性能基准；系统调度和真实后端耗时仍会影响精确完成时间。

几个比较 location 显式选择了 429。另一个 location 保持默认拒绝状态，第二个立即请求得到 503。最后，nginx 对含有显式 burst=0 的可丢弃配置执行语法检查，并拒绝它。正在运行的有效配置与失败候选分开，因此负向语法检查不会打断其他实验，也不能把候选文件存在误当成它已经生效。

让等待策略匹配端点需求

如果希望平滑已接受请求的到达速度，且等待能落在请求截止时间内，可以使用延迟超额。如果后端可以承受有界的立即突发，可以使用 nodelay；部分延迟则在开始节流前提供一个立即通过区间。这些设置本身都不限制已经执行中的长请求数量，不能把到达速率与并发资源占用混成同一个预算。

key 的选择应与速率同样认真。这里用查询参数让不同案例可复现，它有意由客户端控制，不是生产身份方案。客户端能改变 key，就能改变自己消耗哪个预算。按 IP 计数有另一组边界，包括多人共享地址和可信代理处理。应根据真正要限制的主体确定 key，并核实该主体在限流阶段是否已经可信可用。

观测信息应足以区分应用错误、限流拒绝和延迟请求。429 可以说明限流策略，在能提供有意义重试时间时也可以附带 Retry-After，但这个示例不会自动生成该头。最终要验证实际状态、调度和后端行为，而不是认为一个指令名称已经描述完整客户端体验。限流配置是否有效，应由真实请求结果证明。

来源

nginx request limit module，漏桶计数、burst、delay、nodelay 与拒绝状态，已核验 2026-10-15。
RFC 6585 additional HTTP status codes，429 Too Many Requests 的语义，已核验 2026-10-15。
nginx 1.28.0 request-limit source，显式非正 burst 值会被拒绝的解析逻辑，已核验 2026-10-15。

nginx 选择第一个匹配正则，不会计算通用具体程度分数

Mon, 27 Dec 2027 00:00:00 +0000

nginx 不会给所有 location 表达式计算一份通用的具体程度分数。普通前缀按匹配长度选择，精确 location 可以结束搜索，竞争正则则按声明顺序求值。某个表达式在人看来更窄，也可能输给前面更宽的正则。把这些选择规则混在一起，是许多看似仔细的路由变更影响意外路径的原因，必须分别理解每类规则。

坏掉的样子

通用 .css 后缀正则，可以先于后面的 /assets/ 限定正则获胜。后者因为包含目录，看起来似乎更具体，但 nginx 不会比较两个模式在语义上谁更窄。在这里的平面结构中，只要两者都匹配，顺序就决定使用哪个配置。路径更长或正则文字更多，都不是正则之间的额外优先分。

调整普通前缀顺序是另一回事。把 /assets/ 移到 / 之前，不会让它“更优先”；在采用前缀结果时，更长匹配本来就决定它获胜。如果把所有 location 都当成同一个先匹配先使用列表，审阅可能做出无效调整，却漏掉真正控制故障路径的正则顺序。修改文本与修改行为之间，需要通过规则和请求证据连接。

较短的 ^~ 前缀，也不是整个子树的永久保护层。如果存在更长的普通前缀并被选中，较短的标记前缀就不再是抑制正则阶段的候选。因此，新增一个看似无害的更详细前缀，可能让原来停留在标记 location 的请求重新被后缀正则接管。这种变化不能仅凭新增块自身内容看出来。

快速验证

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

使用宿主 Python、Docker 和固定 nginx 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Docker 29.3.1。它构建两份临时配置，分别执行 nginx -t，再通过宿主回环端口发送真实请求。每份配置都只使用平面 location，结束时清理自己的容器、镜像标签和私有网络，不修改既有服务：

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_text(content)
 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()
 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'

prefixes=[
 'location / { return 200 "fallback"; }',
 'location /assets/ { return 200 "asset-prefix"; }',
 'location = /assets/exact.css { return 200 "exact"; }',
 'location ^~ /static/ { return 200 "static-prefix"; }',
 'location /static/dynamic/ { return 200 "dynamic-prefix"; }']
regexes=[r'location ~ \.css$ { return 200 "generic-css"; }',r'location ~ ^/assets/ { return 200 "asset-regex"; }']
for reverse,expected in [(False,'generic-css'),(True,'asset-regex')]:
 ordered_prefixes=list(reversed(prefixes)) if reverse else prefixes
 ordered_regexes=list(reversed(regexes)) if reverse else regexes
 locations='\n'.join(ordered_prefixes+ordered_regexes)+'\n'+r'location ~* \.txt$ { return 200 "case-folded-text"; }'
 with lab(config(locations)) as (container,request):
 cases={'/assets/file.css':expected,'/assets/exact.css':'exact','/static/file.css':'static-prefix','/static/dynamic/file.css':'generic-css','/static/dynamic/plain':'dynamic-prefix','/README.TXT':'case-folded-text','/elsewhere.CSS':'fallback','/elsewhere':'fallback'}
 for path,wanted in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==wanted,(path,status,body)
print('reversing the matching regex declarations changes the winner; the first matching regex is not necessarily the most specific')
print('exact locations and longest-prefix selection ignore declaration order; a longer ordinary prefix can make a shorter ^~ prefix irrelevant')

第一份配置把 .css 正则放在 /assets/ 开头的正则之前，请求 /assets/file.css 返回 generic-css。第二份反转两个正则，相同请求改为返回 asset-regex。请求没有变得更具体或更宽泛，变化的只有两个同时匹配模式的顺序。这为“正则自动选最具体”的说法提供直接反例。

脚本还在两份配置之间反转普通前缀声明，它们相关结果保持稳定。/static/dynamic/plain 仍使用更长普通前缀，无关路径仍进入宽泛默认处理。这个对照把前缀文本重排与正则文本重排分开，不会因为两种操作都叫调整顺序，就假定它们具有相同路由效果。判断改动影响时，应先识别被移动的是哪类块。

精确 /assets/exact.css 在两份配置中都获胜，虽然这个路径也匹配两条正则，它始终返回 exact。实验因此包含一条有意不受正则顺序影响的路径，避免把“第一个匹配正则”说成无条件覆盖所有其他 location 类型的规则。完整优先关系比一句简化口号更能解释边界。

/static/file.css 留在 ^~ /static/ 中，返回 static-prefix。但 /static/dynamic/file.css 具有更长普通前缀，于是 .css 正则仍会被考虑，并返回 generic-css。这验证了 ^~ 对被选中前缀的限定：修饰符属于那个 location，而不是隐藏地继承到每个更深前缀上的保护。

大小写修饰符单独验证。~* 文本文件模式匹配 /README.TXT；区分大小写的 .css 模式不匹配 /elsewhere.CSS，后者进入默认处理。这些结论针对实验中的明确正则和 Linux 环境，不是声称所有文件系统路径或所有平台都遵守相同大小写规则。匹配方式与文件读取方式也应分别判断。

让重叠在审阅中可见

对每条正则，找出也匹配更早表达式的路径，并记录预期由谁处理。测试既要覆盖两个模式重叠，也要覆盖两者都不匹配的情况。只在单条正则孤立存在时测试，无法发现后来有人在前面加入另一个表达式时引入的优先冲突。重叠本身应成为可审阅的契约，而不是偶然顺序。

当精确或前缀 location 能自然表达路由时，可以使用它们，并让有意存在的正则重叠容易理解。正则本身并非错误，但其顺序会成为服务契约的一部分。包含配置发生变化也可能改变有效顺序，因此需要检查完整加载配置，不能只审阅脱离上下文的文件片段，再根据局部排列推断结果。

在已有标记前缀下面增加更长前缀时，重新测试经该路径进入的后缀请求，不要假定旧 ^~ 仍控制它。最后，验证获胜块中的缓存头、代理与访问控制等实际行为。选中预期标记只证明路由，不能证明块内每项策略都正确，更不能替代真实服务处理链的回归检查。

来源

nginx core location directive，第一个匹配正则、前缀优先关系与大小写修饰符，已核验 2026-10-15。
How nginx processes a request，已选 server 内的配置选择，已核验 2026-10-15。
nginx 1.28.0 core implementation，指定版本的前缀与正则 location 搜索行为，已核验 2026-10-15。

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

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。

显式启用 gzip，再验证协商与解码后的字节

Sun, 29 Aug 2027 00:00:00 +0000

gzip 是响应内容编码：nginx 可以发送压缩表示，由接受该编码的客户端解码。启用它需要 gzip on；gzip_types 扩展有资格压缩的 MIME 类型，却不会单独激活压缩。最终结果取决于响应、请求方能力和实际生效配置。只有压缩后仍能正确还原目标内容，较小正文才有价值，不能把“传输字节变少”与“功能已经正确”直接画等号。

坏掉的样子

在 gzip off 下列出 MIME 类型，不会让响应变成 gzip。另一个常见遗漏是 gzip_vary on。nginx 并不会仅因为发生压缩，就无条件添加 Vary: Accept-Encoding；该行为受对应指令控制。共享缓存需要知道哪些请求头维度影响表示选择，否则不同解码能力的客户端可能拿到不合适的已存响应。压缩成功和缓存选择正确是两个需要分别检查的结果。

最小长度设置的契约比名称暗示的更窄。gzip_min_length 根据响应 Content-Length 字段确定长度，不一定知道未指定长度响应的最终大小。因此，一个很短的动态流式响应仍可能被压缩，而同样短的静态文件会因为已知长度低于阈值而跳过压缩。不能从阈值配置推断所有小响应都不会进入压缩路径。

测量方法也可能误导。解压后输出文件的大小，不是压缩传输正文大小；压缩正文字节也不包含全部 HTTP 分帧、响应头和 TLS 流量。.gz 等文件扩展名本身不能证明实际编码。解释任何表面上的带宽节省之前，都应检查真实 Content-Encoding，并解码核对字节，否则可能只是把两种不同计量对象放在一起比较。

快速验证

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

将脚本保存为 check-gzip.py，准备 Python、Docker 和固定镜像后运行。记录环境为 Linux arm64 上的 nginx 1.28.0，以及一个小型 Python 后端。nginx 显式开启三级 gzip，在内置 HTML 资格之外允许 JSON，设置 1,024 字节下限，并显式启用 Vary。服务只发布到宿主回环，实验完成后清理自己的资源：

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 gzip,hashlib
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 self.send_response(200);self.send_header('Content-Type','application/json')
 self.send_header('Connection','close');self.end_headers();self.wfile.write(b'{"ok":true}\n');self.close_connection=True
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
payload=json.dumps({'message':'compressible nginx response '*1000}).encode()
locations='''
location = /disabled.json { gzip off; gzip_types application/json; }
location = /novary.json { gzip_vary off; }
location = /stream { proxy_pass http://backend:8081; }
'''
extra='''
types { application/json json; text/html html; application/octet-stream bin; }
gzip on; gzip_types application/json; gzip_vary on; gzip_min_length 1024; gzip_comp_level 3;
'''
files={name:payload for name in ['large.json','other.bin','page.html','disabled.json','novary.json']};files['tiny.json']=b'{"ok":true}\n'
with lab(config(locations,extra),files,backend) as (_,request):
 results={}
 for encoding in ['gzip','identity','gzip;q=0','br']:
 status,h,b=request('/large.json',headers={'Accept-Encoding':encoding});assert status==200
 if encoding=='gzip':assert h['content-encoding']=='gzip' and gzip.decompress(b)==payload and len(b)<len(payload)
 else:assert 'content-encoding' not in h and b==payload
 assert h['vary']=='Accept-Encoding'
 results[encoding]={'encoding':h.get('content-encoding','identity'),'body_bytes':len(b)}
 for path,encoded in [('/tiny.json',False),('/other.bin',False),('/page.html',True),('/disabled.json',False),('/novary.json',True),('/stream',True)]:
 status,h,b=request(path,headers={'Accept-Encoding':'gzip'});assert status==200
 assert (h.get('content-encoding')=='gzip')==encoded,(path,h)
 decoded=gzip.decompress(b) if encoded else b
 assert decoded==(files['tiny.json'] if path=='/stream' else files[path[1:]])
 if path=='/novary.json':assert 'vary' not in h
 results[path]={'encoding':h.get('content-encoding','identity'),'body_bytes':len(b),'vary':h.get('vary')}
 results['decoded_sha256']=hashlib.sha256(payload).hexdigest()
 print(json.dumps(results,sort_keys=True))

大型合成 JSON 表示共有 28,015 字节。请求携带 Accept-Encoding: gzip 时，记录到的响应传输正文为 246 字节，Python gzip 解码器能逐字节还原原内容。这份负载刻意包含大量重复文本，用于验证压缩确实发生且内容完整；它的压缩比不能当成生产 JSON、JavaScript 或任意文本的收益预测，更不能直接换算成固定页面加速倍数。

接受 identity、设置 gzip;q=0，或只声明 br 的请求，都得到没有 Content-Encoding 的原始字节。质量值为零表示不接受 gzip；声明 Brotli 也不会在此 nginx 配置中自动安装 Brotli 压缩器，而该请求仍允许 identity。对于具备压缩资格的大响应，包括未压缩变体在内，都能看到 Vary: Accept-Encoding，使选择维度得到明确表达。

同一份合成数据按不具压缩资格的二进制类型提供时保持原样；按 HTML 类型提供时，即使没有在 gzip_types 列出 HTML，仍具备压缩资格。另一个 location 显式设置 gzip off，尽管列出了 JSON，也不会压缩。这些对照把类型资格与总开关区分开来，避免把每次没有 Content-Encoding 都误判为客户端协商失败。

12 字节的静态 JSON 响应因为已知长度低于下限而保持未压缩。后端返回相同的 12 字节，但不提供 Content-Length，而以关闭连接结束响应；nginx 将其压缩为 32 字节。因此，下限并不保证所有微小响应都跳过压缩，这份具体的小负载反而增长了。选择策略时需要考虑长度是否已知，不能只根据最终文件大小反推配置一定如何工作。

最后一个 location 保持 gzip 开启，却关闭 gzip_vary。正文仍以 gzip 到达，但没有 Vary 字段。这个对照让缺失缓存选择维度的问题可以直接观察，无需先让真实共享缓存错误交付一次内容。实验核对的是响应头策略；部署后的缓存是否按该维度正确选择，还应通过实际缓存路径验证。

用有代表性的响应调整策略

选择实际字节适合压缩的内容类型。已经压缩的媒体或归档通常很难从再次编码中获益，而重复文本可能显著缩小。这里的字节计数实验没有测量 CPU 成本。忙碌服务选择压缩等级前，应比较代表性大小、不同设置、服务器利用率和客户端延迟，不应把合成数据的高压缩率当成通用容量结论。

经过代理时，响应元数据也要保持准确。Content-Encoding 告诉接收方怎样解码表示，Vary 告诉缓存哪些请求字段影响选择。如果应用已经发送编码响应，应单独审阅那条路径，而不是给未编码字节补一个会误导客户端的头。最终有判定力的验证始终是：协商结果正确、响应头与正文一致，并且实际解码后逐字节匹配目标内容。

来源

nginx gzip module，启用 gzip、MIME 资格、Content-Length 阈值与 Vary，已核验 2026-10-15。
RFC 9110 HTTP Semantics，Accept-Encoding、Content-Encoding 与表示选择，已核验 2026-10-15。

请求限流保护的是 key 所命名的预算

Sat, 28 Aug 2027 00:00:00 +0000

请求速率限制作用于 key 表达的身份，不会自动理解人、账户或端点。limit_req_zone 为这些 key 值保存共享状态，limit_req 则在处理请求时应用对应区域。两个 location 使用相同区域和 key，可以消耗同一份预算。因此，选择变量实际上是在定义公平性与执行边界，并不是只给配置找一个方便填写的字符串。

坏掉的样子

客户端可控标识可能把一个表面上的限制变成许多独立额度。如果修改查询参数就能改变 key，不可信客户端就能选择另一份预算。空 key 更直接：nginx 不会统计 key 求值为空的请求。身份变量缺失时，请求可能无声地离开原本计划的限流范围。只测试正常携带身份的访问，会漏掉这条重要边界。

IP key 衡量的是地址，它可能代表 NAT 或中间层后面的很多用户。转发地址头要先经过明确信任策略，才能成为身份输入。相信任意 X-Forwarded-For，会让调用者制造身份；忽略真实可信代理的地址链，又可能把所有用户放进代理自身的一份预算。两种错误都不能靠提高速率解决，因为问题首先在于限制对象选错了。

共享内存的范围也很重要。区域在同一 nginx 实例的 worker 之间共享，不会自动形成跨无关进程或机器的全局计数器。兼容的平滑 reload 可以保留区域状态。如果假定每次重载配置都会重置全部额度，就可能在测试或恢复操作中，把继续出现的拒绝误判为部署坏了。应区分配置换代、进程换代与共享状态生命周期。

快速验证

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

将脚本保存为 check-limit-keys.py，准备 Python、Docker 和固定镜像后执行。记录环境使用带两个 worker 的 nginx 1.28.0，以及可丢弃 HTTP 后端。额度刻意设为每分钟一个请求，使各次观察落在同一预算区间；不同公开测试 key 隔离案例。监听只发布到宿主回环，结束后清理实验资源，不修改现有站点配置：

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,extra_ports=()):
 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')
 published=[arg for value in (8080,*extra_ports) for arg in ('-p','127.0.0.1::'+str(value))]
 docker('run','-d','--name',containers[0],'--network',name,*published,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;request.network=name
 request.ports={int(key.split('/')[0]):int(value[0]['HostPort']) for key,value in details['NetworkSettings']['Ports'].items() if value}
 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'
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def log_message(self,*args):pass
 def do_GET(self):
 body=json.dumps({'path':self.path,'method':self.command}).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(body)));self.end_headers();self.wfile.write(body)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
from concurrent.futures import ThreadPoolExecutor
extra='''
limit_req_zone $arg_client zone=identity:1m rate=1r/m;
limit_req_zone $binary_remote_addr zone=address:1m rate=1r/m;
limit_req_status 429;
add_header X-Limit $limit_req_status always; add_header X-Worker $pid always;
'''
locations='''
location /a { limit_req zone=identity; proxy_pass http://backend:8081; }
location /b { limit_req zone=identity; proxy_pass http://backend:8081; }
location /dry { limit_req zone=identity; limit_req_dry_run on; proxy_pass http://backend:8081; }
location /ip { limit_req zone=address; proxy_pass http://backend:8081; }
location /open { proxy_pass http://backend:8081; }
'''
configuration=config(locations,extra).replace('worker_processes 1;','worker_processes 2;')
with lab(configuration,backend=backend) as (proxy,request):
 results={}
 assert request('/a?client=one')[0]==200 and request('/b?client=one')[0]==429
 assert request('/a?client=two')[0]==200
 results['same_zone_cross_location']=[200,429];results['changed_untrusted_key']=200
 empty=[request('/a') for _ in range(2)];assert all(r[0]==200 for r in empty)
 assert all(r[1].get('x-limit') is None for r in empty)
 results['empty_keys']=[{'status':r[0],'limit':r[1].get('x-limit')} for r in empty]
 first=request('/ip',headers={'X-Forwarded-For':'192.0.2.1'})
 second=request('/ip',headers={'X-Forwarded-For':'192.0.2.2'})
 assert first[0]==200 and second[0]==429;results['forged_forwarding_header']=[200,429]
 first=request('/dry?client=dry');second=request('/dry?client=dry')
 assert first[0]==second[0]==200 and second[1]['x-limit']=='REJECTED_DRY_RUN'
 results['dry_run']={'status':second[0],'limit':second[1]['x-limit']}
 first=request('/a?client=shared');assert first[0]==200;workers={first[1]['x-worker']}
 deadline=time.monotonic()+8
 while time.monotonic()<deadline and len(workers)<2:
 with ThreadPoolExecutor(max_workers=8) as pool:
 replies=list(pool.map(lambda _:request('/b?client=shared'),range(8)))
 assert all(r[0]==429 for r in replies);workers.update(r[1]['x-worker'] for r in replies)
 assert len(workers)==2,workers
 results['shared_budget_worker_ids']=sorted(workers)
 docker('exec',proxy,'nginx','-s','reload')
 wait(lambda:request('/open')[1]['x-worker'] not in workers)
 reply=request('/a?client=shared');assert reply[0]==429 and reply[1]['x-worker'] not in workers
 results['graceful_reload']={'status':reply[0],'worker':reply[1]['x-worker']}
 print(json.dumps(results,sort_keys=True))

/a?client=one 成功，随后 /b?client=one 返回 429，因为两个 location 使用同一区域。把查询身份改为 two，请求又成功。这适合受控演示，却恰好说明未经验证的查询参数不适合作为抵抗滥用的唯一生产身份。系统确实执行了它收到的 key 规则，但规则选择的主体可能不符合业务意图。

两次不带 client 参数的请求都成功，而且没有 X-Limit 决定值，因为空 key 没有被计数。当身份来自可选请求头或认证结果时，这个对照尤其重要：变量非空的正常流量看起来可能正确受限，而缺少变量的请求却绕过了原本的计数。必须显式测试身份缺失，不能仅从正常路径推断所有请求都在预算内。

按 IP 限制的 location 收到两次携带不同伪造 X-Forwarded-For 的请求，第一次成功，第二次返回 429。这里没有安装 real-IP 信任配置，因此地址 key 仍来自套接字对端。这证明在本次设置中，仅发送不同转发头不会改变配置身份；它并没有认证某个原始互联网用户，也不能被解释为任意代理链的客户端地址恢复已经正确。

dry-run location 对原本会拒绝的请求仍返回 200，但决定头是 REJECTED_DRY_RUN。计数依然发生，只是在该处关闭执行拒绝。仅观察成功响应会隐藏这一区别。评估候选策略时，应读取 dry-run 决定变量，而不是只统计客户端可见的拒绝数，否则容易把“正在记录超额但未执行”误当成“没有超额”。

对于新的共享 key，第一次请求成功，后续从两个已观察 worker 进程 ID 返回的请求都得到 429。随后 nginx 用同一区域配置执行平滑 reload，新 worker 仍拒绝该 key，证明预算状态被保留，没有重置。测试先等待新 worker 身份出现，再把结果归因于重载，避免实际仍由旧 worker 处理却声称已验证新进程行为。

一起定义身份、范围和观测方式

先决定预算应属于地址、已认证账户、路由还是它们的组合，并验证输入在限流阶段已经存在且可信。跨 location 共享区域可以有意建立一份服务预算，分开区域则产生不同计数。不要以为 location 名称会自动成为 key 的一部分；如果表达式没有包含那个维度，就不能期待它提供对应隔离。

区域内存需要按 key 基数规划，不能只看到请求量。文档说明每个 key 的状态在六十四位平台占一百二十八字节，在三十二位平台占六十四字节；这里的位数指平台架构，不是 key 的位数。存储耗尽可能淘汰旧状态，如果仍无法分配，则可能拒绝请求。这个实验验证执行语义，没有测量最大 key 容量，也没有把文档中的近似容量当成本机压测结果。

变更之后还要检查有效配置与决定遥测，区分空 key 不计数、dry run 放行、真正拒绝和 reload 保留状态。单实例限制正常工作，并不能证明全局租户配额已经实现；一个请求返回 429，也不能独自说明究竟消耗了哪个预期用户或路由预算。限流效果需要与身份语义一起解释，才有实际约束价值。

来源

nginx request limit module，共享 key 状态、空 key、dry run、内存大小与决定变量，已核验 2026-10-15。
nginx real IP module，从代理信息推导客户端地址时的信任边界，已核验 2026-10-15。
RFC 6585 additional HTTP status codes，429 与受限主体识别，已核验 2026-10-15。
nginx 1.28.0 request-limit source，兼容 reload 过程中共享区域状态的复用，已核验 2026-10-15。

反向代理需要明确的请求头信任边界

Fri, 27 Aug 2027 00:00:00 +0000

反向代理接受客户端连接，再单独请求上游应用。因此，应用套接字看到的对端是代理，较早客户端的信息则可能通过请求头传入。这些头部只有在部署明确谁可以设置、如何验证时才有可信含义。请求经过代理，不会自动让所有转发身份或协议声明变得可靠；需要把网络连接事实与请求携带的文本声明区分开。

坏掉的样子

客户端到达代理前就可以提供 X-Forwarded-For。普通转发可能保留它，$proxy_add_x_forwarded_for 也只是追加当前对端地址，不会移除不可信前缀。如果应用盲信第一个地址，就可能把请求归属到客户端自行选择的值。正确解释取决于真实可信代理链，不能因为字段名包含 Forwarded 就赋予整条列表相同信任。

Host 处理是独立决策。nginx 默认上游 Host 基于代理目标，不会自动采用客户端访问的公共 Host。因此，构造绝对跳转或选择虚拟主机的应用，在代理后可能表现不同。应只转发预期主机上下文，并应用服务自己的可接受主机名策略；复制头部不等于验证其中名字，也不能替代虚拟服务器入口限制。

代理也不保证后端细节完全不暴露。响应头、跳转、正文、诊断信息或其他公开配置，都可能披露源站信息。限制直接访问和控制特定响应字段很有价值，但这不同于声称一条 proxy_pass 就能隐藏全部上游身份，或提供所需的所有传输保护。地址隐藏、访问控制和加密需要分别依据真实部署判断。

快速验证

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

使用宿主 Python、Docker，以及固定 nginx 和 Python 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Python 3.11.16、Docker 29.3.1。它创建私有 Docker 网络与真实回显后端，只把代理发布到宿主回环，验证配置并清理自己的资源，不涉及生产端点或凭据。实验中的伪造值使用文档专用地址：

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_text(content)
 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()
 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'

backend=r'''from http.server import BaseHTTPRequestHandler,HTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 body=self.rfile.read(int(self.headers.get('Content-Length','0')))
 document={'path':self.path,'method':self.command,'body':body.decode(),'headers':{key:self.headers.get(key) for key in ['Host','X-Forwarded-For','X-Real-IP','X-Forwarded-Proto','X-Forwarded-Host']}}
 data=json.dumps(document).encode()
 self.send_response(200);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(data)));self.send_header('X-Backend-Info','fixture-node');self.end_headers();self.wfile.write(data)
 do_POST=do_GET
 def log_message(self,*args):pass
HTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''

locations=r'''
location /default { proxy_pass http://backend:8081; }
location /append { proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_pass http://backend:8081; }
location /edge {
 proxy_set_header Host $host;
 proxy_set_header X-Forwarded-For $remote_addr;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_set_header X-Forwarded-Host $host;
 proxy_hide_header X-Backend-Info;
 proxy_pass http://backend:8081;
}
'''
with lab(config(locations,'server_tokens off;'),backend=backend) as (container,request):
 forged={'Host':'public.example','X-Forwarded-For':'198.51.100.77','X-Forwarded-Proto':'forged-scheme','X-Real-IP':'198.51.100.88'}
 status,headers,body=request('/default',headers=forged);plain=json.loads(body)
 assert status==200 and plain['headers']['Host']=='backend:8081'
 assert plain['headers']['X-Forwarded-For']=='198.51.100.77' and plain['headers']['X-Forwarded-Proto']=='forged-scheme'
 assert headers['x-backend-info']=='fixture-node'
 status,headers,body=request('/append',headers=forged);appended=json.loads(body)['headers']['X-Forwarded-For'].split(', ')
 assert status==200 and len(appended)==2 and appended[0]=='198.51.100.77'
 status,headers,body=request('/edge',headers=forged);edge=json.loads(body)['headers']
 assert status==200 and edge['Host']==edge['X-Forwarded-Host']=='public.example'
 assert edge['X-Forwarded-For']==edge['X-Real-IP']==appended[-1]
 assert edge['X-Forwarded-For'] not in ['198.51.100.77','198.51.100.88'] and edge['X-Forwarded-Proto']=='http'
 assert 'x-backend-info' not in headers and headers['server']=='nginx'
 print('ordinary forwarding preserves forged forwarding headers and defaults Host to the upstream authority')
 print('append retains the untrusted prefix; the direct-client edge configuration replaces it with the actual socket peer and scheme')
 print('explicit response-header suppression removes one backend field, while server_tokens off still exposes the nginx product name')

每个请求都把 Host 设为 public.example，并携带特意伪造的转发值。默认路由向后端发送 Host: backend:8081，同时保留伪造的 X-Forwarded-For 和 X-Forwarded-Proto。这直接证明普通代理转发不是身份清洗步骤，也不会自动保留公共主机名。后端回显让这些差异可见，不需要仅凭配置推理。

追加路由使用 $proxy_add_x_forwarded_for，后端收到两个逗号分隔地址：客户端提供的地址在前，nginx 观察到的套接字对端在后。原本不可信的前缀仍在。追加有用连接上下文，不会让整个结果列表同样可信；在这个直接面对客户端的结构中，盲信最左地址就会破坏预期边界。

入口路由用 $remote_addr 替换 X-Forwarded-For 和 X-Real-IP，用 $scheme 设置转发协议，并显式传入选择的主机上下文。后端收到真实观察到的对端值，不是两个伪造地址之一；本实验有意使用普通 HTTP，所以协议为 http。测试跨请求比较这些值，不假定 Docker 网桥一定分配某个固定地址。

套接字对端可能反映 Docker 网络路径，这不表示能穿过所有 NAT 或更早代理，恢复任意互联网用户地址。如果入口本身位于可信负载均衡器之后，部署需要有意定义如何接受该跳的信息。本例验证的是直接客户端信任边界，不覆盖所有代理链；应用不能把示例中正确的取值规则无条件搬到不同拓扑。

后端还返回 X-Backend-Info: fixture-node。默认路由会暴露它，入口路由通过明确的 proxy_hide_header 删除它。关闭 server_tokens 后，响应仍包含 Server: nginx。这把隐藏一个后端字段，与隐藏代理产品名或证明其他响应内容没有实现细节区分开。一个字段消失，不等于所有信息泄露渠道都消失。

连接网络访问规则与头部解释

后端依赖代理建立的上下文时，应限制哪些调用者可以直接访问它。如果使用 real IP 模块，可信代理地址范围应准确，并确保最终地址解释与应用自身信任设置一致。过宽信任范围可能让非预期调用者提供看似权威的转发信息，因此不能把网络可达与可信来源简单画等号。

明确 TLS 在哪里终止，以及上游连接是否也需要加密和证书验证。nginx 在当前一跳观察到的协议，不会自动描述更早一跳。跳转、安全 Cookie 和生成 URL 如果依赖转发协议或主机名，就应通过实际部署链路测试。只验证内部 HTTP 回显，不能宣布外部 HTTPS 行为也正确。

最后，同时检查应用收到的请求和客户端收到的响应。头部配置、网络隔离和信息披露控制，分别回答不同问题。两侧证据可以让组合行为可审阅，而不是假定代理会默默补上每个缺失保证。明确事实来源，才能让应用正确使用代理提供的上下文。

来源

nginx HTTP proxy module，默认 Host 处理、转发头与响应头隐藏，已核验 2026-10-15。
nginx real IP module，显式信任的地址来源与代理链，已核验 2026-10-15。
nginx core server_tokens and variables，套接字对端地址、请求协议与服务器版本披露，已核验 2026-10-15。

nginx 匹配规范化路径，并可能再次选择 location

Thu, 26 Aug 2027 00:00:00 +0000

nginx location 匹配使用规范化后的 URI 路径，而不是完全未经处理的请求目标文本。百分号编码字符会被解码，相对路径组件会被消解，相邻斜杠也可能按配置合并。之后的处理还能再次改变当前 URI，并触发新的 location 搜索。当请求似乎进入了与原始拼写不同的处理器时，需要同时理解这两类转换，而不是只比较配置中的字面前缀。

坏掉的样子

只根据原始请求文本判断的路径过滤器，可能与 nginx 路由视图不一致。编码斜杠可以变成路径分隔符，点段可以移除前面的组件，后端还可能采用自己的解码规则。因此，安全与路由决策需要在每个边界约定解释方式，不能假定所有组件看到完全相同的路径字符串。否则同一请求可能在检查时属于一个家族，处理时却属于另一个。

只记录 $uri 也可能掩盖实际输入。它表示当前规范化 URI，并可能在请求处理期间改变；$request_uri 则保留完整原始 URI，包括原始查询字符串。两者不能互相完全替代：前者解释当前路由，后者帮助重建客户端实际请求。诊断时应按问题选择字段，而不是把一个名字相近的变量当成全部路径信息。

index 和 try_files 还会引入另一类转换。目录请求可以内部变成索引文件请求，文件查找失败可以内部跳到回退 URI，使不同 location 和参数生效。所以，最初的前缀匹配不一定就是产生最终响应的配置。若只验证入口匹配，而忽略后续内容处理，就可能漏掉访问控制、缓存或响应状态发生变化的位置。

快速验证

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

使用宿主 Python、Docker 和固定 nginx 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Docker 29.3.1。它构建并检查临时配置，只发布宿主回环端口，发送客户端未预先规范化的请求目标，最后删除自身镜像、容器和网络。这样可以观察 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_text(content)
 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()
 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'

locations=r'''
location / { return 200 "$uri|$request_uri|$args"; }
location /protected/ { return 403 "blocked"; }
location /docs/ { try_files $uri $uri/ /fallback?reason=missing; }
location = /docs/index.html { return 200 "$uri|$request_uri|$args"; }
location = /fallback { return 200 "$uri|$request_uri|$args"; }
'''
with lab(config(locations),{'docs/index.html':'stored-index'}) as (container,request):
 cases={
 '/a//b/../c?x=1':'/a/c|/a//b/../c?x=1|x=1',
 '/a%2Fb/%2e%2e/c?x=1':'/a/c|/a%2Fb/%2e%2e/c?x=1|x=1',
 '/Protected/item':'/Protected/item|/Protected/item|',
 '/docs/':'/docs/index.html|/docs/|',
 '/docs/missing?x=1':'/fallback|/docs/missing?x=1|reason=missing'}
 for path,expected in cases.items():
 status,headers,body=request(path);assert status==200 and body.decode()==expected,(path,status,body)
 for path in ['/protected/item','/protected%2Fitem','/a/../protected/item']:assert request(path)[0]==403,path
 assert request('/bad%ZZ')[0]==400
 print('matching uses normalized paths: percent-decoding, dot segments, and merged slashes differ from the original request URI')
 print('index and try_files internal redirects choose another location; request_uri remains original while uri and args can change')

请求 /a//b/../c?x=1 得到当前 URI /a/c，原始请求 URI 仍为 /a//b/../c?x=1，参数仍为 x=1。这在实测默认配置下展示斜杠合并和点段消解。响应同时包含三个字段，能够直接比较含义，不需要从最终页面内容反向猜测路径到底经过哪些转换。

编码请求 /a%2Fb/%2e%2e/c?x=1 到达同样的当前路径 /a/c，但 request_uri 仍保留原始编码拼写。它说明百分号解码参与路由前的规范化。测试没有依赖浏览器地址栏，因为浏览器可能在发送前已经改写路径。只有知道线上真正收到的请求目标，才能正确解释服务器行为。

受保护前缀对 /protected/item、/protected%2Fitem 和 /a/../protected/item 都返回 403，因为规范化后都属于该路径家族。在这个 Linux 环境中，/Protected/item 因大小写不同而进入普通默认处理。无效百分号编码 %ZZ 则得到 HTTP 400，而不是被当成成功通向任意内容的路径。这些是不同边界，不能混成一个通用字符串比较。

实验放置了真实 /srv/docs/index.html。请求 /docs/ 经 index 处理后进入精确的 /docs/index.html location，该块返回诊断标记，而不是存储文件本身的正文。原始 request_uri 仍是 /docs/。这让内部 location 变化变得可见，虽然客户端没有收到跳转状态，也没有自行发起第二次请求。

对于 /docs/missing?x=1，try_files 找不到文件或目录，会内部选择 /fallback?reason=missing。响应报告当前 URI 为 /fallback，原始请求 URI 为 /docs/missing?x=1，当前参数为 reason=missing。本例回退中显式查询替换了早先参数；如果希望保留原参数，需要明确配置，不能认为所有内部跳转都会自动保持它们。

沿完整请求链验证路径契约

修改路由时，测试有代表性的编码形式、重复斜杠、点段、缺失文件和目录请求。如果客户端、代理与应用的规范化方式不同，集成验证应包含真实组件。这个小实验建立的是所选配置下的 nginx 行为，不证明所有上游框架或安全过滤器都以相同方式解释相同字节。跨组件一致性需要另外的实际请求证据。

诊断中有意选择原始和当前 URI 字段，同时认识到查询字符串可能包含敏感信息，只记录运维任务真正需要的内容。内部跳转可能改变最终处理器和日志上下文，所以除了首次匹配，也要验证事件最终记录在哪里。否则日志缺失或字段变化可能被误判成请求没有到达。

回退行为应明确。缺失资源不应意外变成成功的应用页面，从而掩盖部署错误；受保护路径也不应在重写后落入无关回退。语法检查能够发现配置格式问题，带有明确状态、字段和正文断言的请求，才能验证用户最终实际收到的行为。这两种证据需要一起使用。

来源

nginx core location, try_files, and variables，URI 规范化、内部跳转以及原始与当前 URI，已核验 2026-10-15。
How nginx processes a request，index 处理与后续 location 选择，已核验 2026-10-15。
nginx 1.28.0 core implementation，实测版本的 location 搜索与内部跳转行为，已核验 2026-10-15。

结构化 nginx 日志需要同时约定转义和字段类型

Thu, 15 Jul 2027 00:00:00 +0000

看起来像 JSON 的 log_format，不一定能可靠地产生结构化事件。nginx 把变量值代入文本，而变量可能包含引号、反斜杠、控制字符，也可能完全没有数据。正确字符串转义与正确字段类型是两个独立要求。用真实解析器检查输出，能发现肉眼查看配置或 nginx -t 成功无法证明的问题，避免上线后才发现部分日志无法进入查询系统。

坏掉的样子

把 User-Agent 原样插入带引号的 JSON 字段，遇到请求头中的引号就会失败。关闭转义不会更安全，只会让请求字符改变外层记录语法。nginx 默认日志转义则有另一种问题：它可能使用十六进制 \xXX 序列，而这不是合法 JSON 字符串转义。日志适合人阅读，不代表它符合另一种数据格式的语法。

加入 escape=json 可以处理 JSON 字符串转义，但不会自动添加引号、提供 null，或把变量转换成数字。对于本地生成的响应，上游耗时可能根本不存在。如果没有定义可选值的表示方式，就直接不加引号输出，字段可能在语法上缺值；即使实际存在的字符全部转义正确，整个 JSON 仍然无效。

缺失值表示也取决于实测版本的转义路径。nginx 1.28.0 默认转义会为找不到的变量写入短横线，JSON 转义则不写变量文本，所以外面的双引号最终成为空字符串。解析器还必须把这种情况与变量本身确实包含短横线、或包含多次上游尝试列表的情况区分开，不能把所有形式都硬当成同一个数字。

快速验证

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

使用宿主 Python、Docker 和固定 nginx 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Docker 29.3.1。它构建包含四种日志格式的临时配置，验证语法，发送两次真实 HTTP 请求，解析生成文件，最后清理自己的容器、镜像标签和网络。请求头都是公开测试字符串，不读取真实凭据或业务日志：

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_text(content)
 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()
 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'

extra=r'''
log_format default_escape '{"agent":"$http_user_agent","upstream_time":"$upstream_response_time"}';
log_format raw escape=none '{"agent":"$http_user_agent"}';
log_format numeric escape=json '{"upstream_time":$upstream_response_time}';
log_format structured escape=json '{"agent":"$http_user_agent","upstream_time":"$upstream_response_time","status":$status,"request_id":"$request_id"}';
'''
locations=r'''
access_log /tmp/default.json default_escape;
access_log /tmp/raw.json raw;
access_log /tmp/numeric.json numeric;
access_log /tmp/structured.json structured;
location / { return 204; }
'''
with lab(config(locations,extra)) as (container,request):
 agent='reader "quoted" '+chr(92)+' path'+chr(9)+'tab'
 assert request('/local',headers={'User-Agent':agent})[0]==204
 assert request('/local',headers={'User-Agent':'plain'})[0]==204
 def lines(path):return docker('exec',container,'cat',path).stdout.splitlines()
 wait(lambda:len(lines('/tmp/structured.json'))==2)
 default=lines('/tmp/default.json');raw=lines('/tmp/raw.json');numeric=lines('/tmp/numeric.json');structured=list(map(json.loads,lines('/tmp/structured.json')))
 for line in [default[0],raw[0]]:
 try:json.loads(line)
 except json.JSONDecodeError:pass
 else:raise AssertionError('non-JSON escaping unexpectedly formed valid JSON')
 assert r'\x22' in default[0]
 assert json.loads(default[1])=={'agent':'plain','upstream_time':'-'}
 assert json.loads(raw[1])=={'agent':'plain'}
 for line in numeric:
 try:json.loads(line)
 except json.JSONDecodeError:pass
 else:raise AssertionError('unquoted missing timing unexpectedly formed valid JSON')
 assert [row['agent'] for row in structured]==[agent,'plain']
 assert all(row['status']==204 and row['upstream_time']=='' for row in structured)
 identifiers=[row['request_id'] for row in structured]
 assert len(set(identifiers))==2 and all(len(value)==32 and int(value,16)>=0 for value in identifiers)
 print('escape=json preserves quotes, backslashes and tabs as valid JSON strings; both default and no escaping break JSON on the same public header')
 print('default escaping writes a dash for the absent timing, while JSON escaping writes an empty string in the quoted field')
 print('an unavailable upstream timing is empty under JSON escaping, so emitting it unquoted still creates invalid JSON')
 print('structured records parse with a numeric status, explicit empty timing string and distinct nginx-generated request IDs')

第一个请求的 User-Agent 包含引号、一个反斜杠和制表符，第二个只包含 plain。两者都得到本地 204 响应，不发生上游请求。这有意把特殊字符串与缺失耗时组合起来，分别检验转义和可选值处理，不只依赖普通字母数字头部。测试输入需要能触及格式边界，才能暴露看起来正常的配置缺陷。

第一个请求的默认转义记录包含 \x22，无法通过 JSON 解析；不转义记录也因原始引号破坏外层字符串而失败。普通请求头对照说明，一个格式可以在常见输入下看似正确，却对另一个有效头部值失败。因此，少量肉眼可读日志不是充分验证，尤其无法覆盖客户端能够控制的字符串内容。

默认格式的普通记录，可以解析出带引号的短横线耗时；JSON 转义的结构化格式则得到空耗时字符串。这些实际观察与指定版本日志源码一致。区别对于采集器很重要：如果它假定 nginx 无论使用哪种格式选项，都用同一个缺失值标记，就可能错误解析或丢弃合法记录。版本与格式属于解析契约的一部分。

故意不给耗时加引号的格式，对两个请求都无效。JSON 转义无法把不存在的变量变成数字，所以冒号后面缺少值。结构化格式给可选耗时加引号，保持记录有效，同时不把缺少测量伪装成耗时零秒。缺失与零具有不同含义，不能为了让图表好看而在采集时悄悄合并。

两条结构化记录都成功解析，解码后的 User-Agent 与输入完全相同，status 是数值 204，可选耗时为空字符串。两个 nginx 生成的请求 ID 是不同的三十二位十六进制字符串。实验核对解析后的含义，而不是只检查一行有没有花括号；这样才能证明转义既保留内容，又没有破坏字段结构。

定义采集器应该接受什么

选择稳定字段名和类型，并说明缺失值。上游测量可能包含多个尝试值，保留字符串有时比强行写成单个数字更准确。如果采集器要转换成结构化尝试列表，应为转换定义明确语法和错误处理，不要把异常记录静默归零。原始记录与转换结果都需要足以定位解析差异的证据。

在采集边界同时验证文本编码与 JSON 转义。本实验覆盖包含特殊 ASCII 字符的普通文本，不声称任意无效字节序列都会变成合法 Unicode JSON。解析失败应可观测，避免事故期间有问题的记录悄悄消失，导致查询结果看似完整，实际已经漏掉最需要分析的一批请求。

只记录必要请求数据，并设置合理保留期和访问权限。正确转义的字段仍可能包含敏感信息或不可信身份声明。日志传送和查询全链路需要单独验证：本地 JSON 有效建立了有用契约，却不证明轮转、采集、传输和保留能够保存每一条事件。格式正确只是可靠日志处理的一部分。

来源

nginx HTTP log module，日志格式、转义模式与请求完成记录，已核验 2026-10-15。
nginx 1.28.0 log implementation，默认与 JSON 转义对缺失变量的不同处理，已核验 2026-10-15。
nginx core variables，请求标识与 HTTP 请求变量，已核验 2026-10-15。

过期缓存需要明确的重新验证与陈旧响应策略

Thu, 24 Jun 2027 00:00:00 +0000

nginx 代理缓存需要分别作出几项决定：怎样识别已存响应，什么时候允许读取，什么时候允许保存新响应，以及过期副本还能怎样使用。如果把这些都看成一个 TTL 设置，故障就很难解释。验证时应同时观察请求实际经过的路径与交付字节，而不只是确认 nginx 接受了配置文件。

存储容量与新鲜度分开看

proxy_cache_path 声明磁盘存储位置及保存元数据的共享内存 keys_zone，proxy_cache 再为请求启用这个区域。元数据区大小不等于正文缓存容量。max_size 由缓存维护机制管理，不是瞬时硬磁盘配额；inactive 保留策略也不是响应的新鲜度寿命。已经过期的响应仍可能留在存储中，用于后续重新验证。

默认缓存键为 $scheme$proxy_host$request_uri，其中 request_uri 已经包含查询串，后面再加 $is_args$args 就重复拼接了参数。也不能随意替换成规范化后的 URI，或遗漏会改变表示的输入。默认启用 HEAD 转换，因此 GET 与 HEAD 共享相应缓存行为；关闭转换时，就需要在缓存键中考虑请求方法。

核对真正生效的响应策略

proxy_cache_valid 按状态码提供配置寿命，但正常处理的源站新鲜度头具有更高优先级。X-Accel-Expires 还有自己的优先顺序；它不存在时，Cache-Control 和 Expires 才参与相应设置。忽略这些头会改变实际契约。下面的实验里，源站 max-age 为一秒，覆盖了配置的六十秒；no-store 则阻止响应进入存储。

proxy_cache_revalidate 让过期条目使用 ETag、Last-Modified 等验证器发送条件请求。匹配的 304 可以保留正文并更新元数据，变化后的 200 则提供替代字节。但重新验证不等于异步刷新。后台更新是另一项指令，还需要允许在更新期间返回旧内容，不能仅凭某一个开关推断整套刷新方式。

坏掉的样子

proxy_cache_bypass 控制不从缓存读取，proxy_no_cache 控制不保存新响应。要求两者都成立的路由，需要分别表达两个决策。一次绕过也不意味着已经清除了原有条目。实验让这两项指令使用同一个专用测试头，并验证绕过之后，原有副本依然可用。这个头只是实验开关，不能当作真实身份认证或权限策略。

proxy_cache_use_stale http_500 允许在上游返回 500 时使用已有陈旧副本；完全冷的键没有副本可用，因此不会凭空获得保护。这项指令本身没有规定最大陈旧秒数。源站 stale-if-error 时间窗的优先级低于这些指令参数，额外加上它也不能限制这里的设置。启用之前必须先决定旧内容在业务上是否仍然可接受。

否则，一个表面成功的响应可能正在隐藏源站故障，或者继续交付已经不该使用的数据。应把上游结果、nginx 缓存状态和返回正文一起记录。配置语法检查不能证明账户隔离，一次热缓存命中也不代表并发冷加载正常。缓存锁、容量压力下的保留行为和多工作进程模式，都需要单独验证，不能从本次顺序实验推导出来。

快速验证

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

需要 POSIX 环境、C 编译器、make、curl、tar 以及 Python 3.11 或更新版本。本次在 macOS 上使用 clang 21.0.0、Python 3.14.4 和 nginx 1.30.4 执行。下列命令只编译一个独立的 HTTP 实验程序，不安装到系统，也不用 sudo；关闭 rewrite 和 gzip 模块以避免它们的外部依赖。这不是部署 TLS 服务的配置教程。

nginx_lab=$(mktemp -d)
curl --fail --location --output "$nginx_lab/nginx.tar.gz" https://nginx.org/download/nginx-1.30.4.tar.gz
tar -xzf "$nginx_lab/nginx.tar.gz" -C "$nginx_lab"
cd "$nginx_lab/nginx-1.30.4"
./configure --prefix="$nginx_lab/install" --without-http_rewrite_module --without-http_gzip_module
make -j2
export NGINX_BIN="$nginx_lab/nginx-1.30.4/objs/nginx"

在同一个 shell 中用 python3 执行 Python 代码。程序创建自己的配置和缓存目录，先检查语法，再在选定的回环端口启动源站与 nginx；两次短暂等待用于跨过真实到期时间。结束时关闭自己启动的代理进程和源站，仅移除临时运行目录。源码下载需要外网，实验请求全部留在本机，不操作现有 nginx 服务。

import hashlib
import os
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, HTTPServer
from pathlib import Path
import signal
import socket
import subprocess
from tempfile import TemporaryDirectory
from threading import Thread
import time

state = {"body": b"A", "fail": False}
seen = []


class Origin(BaseHTTPRequestHandler):
 def log_message(self, *_):
 pass

 def do_GET(self):
 tag = '"' + hashlib.sha256(state["body"]).hexdigest() + '"'
 conditional = self.headers.get("If-None-Match")
 if self.path == "/short" and state["fail"]:
 status, body = 500, b"failure"
 elif conditional == tag:
 status, body = 304, b""
 else:
 status, body = 200, state["body"]
 directive = "max-age=1" if self.path == "/short" else "max-age=60"
 if self.path == "/no-store" or status == 500:
 directive = "no-store"
 seen.append((self.path, status, conditional))
 self.send_response(status)
 self.send_header("Cache-Control", directive)
 if status != 500:
 self.send_header("ETag", tag)
 if status != 304:
 self.send_header("Content-Length", str(len(body)))
 self.end_headers()
 self.wfile.write(body)


origin = HTTPServer(("127.0.0.1", 0), Origin)
worker = Thread(target=origin.serve_forever)
worker.start()
try:
 with TemporaryDirectory(prefix="nginx-cache-lab-") as directory:
 root = Path(directory)
 with socket.socket() as reservation:
 reservation.bind(("127.0.0.1", 0))
 port = reservation.getsockname()[1]
 config = root / "nginx.conf"
 config.write_text(f"""
pid nginx.pid;
error_log stderr error;
events {{ worker_connections 64; }}
http {{
 access_log off;
 proxy_cache_path "{root}/cache" keys_zone=lab:1m max_size=10m;
 server {{
 listen 127.0.0.1:{port};
 location / {{
 proxy_pass http://127.0.0.1:{origin.server_port};
 proxy_cache lab;
 proxy_cache_valid 200 60s;
 proxy_cache_revalidate on;
 proxy_cache_use_stale http_500;
 proxy_cache_bypass $http_x_lab_bypass;
 proxy_no_cache $http_x_lab_bypass;
 proxy_connect_timeout 2s;
 proxy_read_timeout 2s;
 add_header X-Lab-Cache $upstream_cache_status always;
 }}
 }}
}}
""", encoding="utf-8")
 command = [os.environ["NGINX_BIN"], "-p", str(root) + "/",
 "-c", str(config), "-e", "stderr"]
 checked = subprocess.run(command + ["-t"], capture_output=True, text=True)
 assert checked.returncode == 0, checked.stderr
 process = subprocess.Popen(command + ["-g", "daemon off; master_process off;"],
 stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, text=True)
 try:
 deadline = time.monotonic() + 5
 while True:
 assert process.poll() is None, "nginx exited during startup"
 try:
 with socket.create_connection(("127.0.0.1", port), timeout=0.1):
 break
 except OSError:
 if time.monotonic() >= deadline:
 raise TimeoutError("nginx did not become ready")
 time.sleep(0.05)

 def get(path, expected, body, bypass=False):
 connection = HTTPConnection("127.0.0.1", port, timeout=3)
 try:
 connection.request("GET", path, headers={"X-Lab-Bypass": "1"} if bypass else {})
 response = connection.getresponse()
 actual = (response.status, response.getheader("X-Lab-Cache"), response.read())
 assert actual == (200, expected, body), actual
 print(path, expected, body.decode())
 finally:
 connection.close()

 get("/long", "MISS", b"A")
 get("/long", "HIT", b"A")
 state["body"] = b"B"
 get("/long", "BYPASS", b"B", bypass=True)
 get("/long", "HIT", b"A")
 assert sum(path == "/long" for path, _, _ in seen) == 2

 get("/short", "MISS", b"B")
 time.sleep(2.1)
 get("/short", "REVALIDATED", b"B")
 assert seen[-1][1:] == (304, '"' + hashlib.sha256(b"B").hexdigest() + '"')
 state["fail"] = True
 time.sleep(2.1)
 get("/short", "STALE", b"B")
 assert seen[-1][1] == 500
 state.update(body=b"C", fail=False)
 get("/short", "EXPIRED", b"C")
 get("/short", "HIT", b"C")
 get("/no-store", "MISS", b"C")
 get("/no-store", "MISS", b"C")
 assert sum(path == "/no-store" for path, _, _ in seen) == 2
 finally:
 if process.poll() is None:
 process.send_signal(signal.SIGQUIT)
 try:
 _, errors = process.communicate(timeout=5)
 except subprocess.TimeoutExpired:
 process.kill()
 process.communicate()
 raise
 assert process.returncode == 0, errors
finally:
 origin.shutdown()
 worker.join()
 origin.server_close()

长寿命路径依次报告 MISS A、HIT A、BYPASS B、HIT A。源站在这条路径只收到两次请求，说明绕过请求获取了 B，却没有把它保存成新的共享副本，也没有删除之前的 A。短寿命路径先报告 MISS B；到期之后报告 REVALIDATED B，源站记录同时确认它确实收到正确的条件 ETag，并返回了 304。

注入源站 500 后，代理报告 STALE B，继续交付原来的正文。源站恢复并提供 C 后，EXPIRED C 替换缓存内容，接下来的访问成为 HIT C。两次 no-store 请求都保持 MISS，且都抵达源站。这里检查的是实际状态和字节，不把日志里出现一个状态词单独当作功能证明。

这些结果来自真实 nginx 的单进程隔离实验，不覆盖后台刷新、分布式失效、生产授权、磁盘压力处理或所有陈旧策略组合。真实发布还需要结合对应版本、完整配置和实际流量补齐这些范围。保留这种边界，才能区分“某条配置路径已经测过”和“整个代理部署已经验收”。

来源

nginx 代理模块，缓存键、头字段优先级、重新验证、绕过、保存和陈旧策略，已核验 2026-10-15。
nginx 编译配置，构建前缀和可选模块依赖，已核验 2026-10-15。
nginx 内容缓存指南，磁盘存储、共享元数据和缓存维护，已核验 2026-10-15。
RFC 9111：陈旧响应，新鲜度与允许使用旧响应的条件，已核验 2026-10-15。

按 nginx 均衡方法实际做出的决定来选择策略

Tue, 18 May 2027 00:00:00 +0000

upstream 组列出候选后端端点，均衡方法从符合条件的节点中选择目标。轮询按权重分配选择，最少连接考虑活动连接与权重，哈希方法则根据指定 key 建立亲和性。这些决定描述路由策略，不会自动测量 CPU 利用率，不保证响应时间相等，也不会在节点消失时让本地会话状态自动获得持久性。选择方法之前，应先明确希望它依据什么信号决策。

坏掉的样子

常见测量错误是看错地址。curl 的 remote IP 标识 curl 实际连接的服务器，在这种架构里通常就是代理。访问日志里的客户端地址字段，同样不是后端分布报告。要评估节点选择，应查看真正的上游地址或受控后端身份；如果重试可能访问多个节点，还要保留各次尝试信息。不能把入口连接信息当成后端选择结果。

请求数均匀不代表工作量均匀。长报表和很小的缓存响应都算一个请求，却可能占用完全不同的资源。配置权重表达预期相对份额，不是自动测得的机器容量。把权重翻倍，不能证明不同后端的每核负载或延迟已经相等。权重是否合理，需要代表性请求成本和节点能力支持，而不是只依据某个硬件参数作推断。

亲和性有另一组失败方式。很多用户可能共享同一源地址，所以 IP 哈希可能集中流量，而不是按个人均匀分布。节点失败或成员变化会改变落点，本地会话状态不会仅因为请求换了机器就一起移动。ip_hash 也不应被描述成 nginx 可配置的一致性哈希环；显式 hash ... consistent 是另一种独立方法，不能把两种策略的性质混用。

快速验证

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

将脚本保存为 check-balancing.py，准备 Python、Docker 和固定镜像后执行。记录环境使用单个 nginx 1.28.0 worker，以及一个可丢弃后端容器中不同端口上的两个可识别 HTTP 节点。共享机器是有意安排：实验测量选择结果，不比较硬件容量。客户端只通过宿主回环访问，结束后清理自己的资源：

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,extra_ports=()):
 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')
 published=[arg for value in (8080,*extra_ports) for arg in ('-p','127.0.0.1::'+str(value))]
 docker('run','-d','--name',containers[0],'--network',name,*published,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;request.network=name
 request.ports={int(key.split('/')[0]):int(value[0]['HostPort']) for key,value in details['NetworkSettings']['Ports'].items() if value}
 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'
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
from urllib.parse import urlsplit,parse_qs
import itertools,json,threading
lock=threading.Lock();ids=itertools.count(1);counts={'A':0,'B':0};active={'A':0,'B':0};faults={'A':200,'B':200};gates={}
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def setup(self):super().setup();self.ident=next(ids)
 def log_message(self,*args):pass
 def do_GET(self):
 parsed=urlsplit(self.path);label=self.server.label;code=200
 if label=='control':
 query=parse_qs(parsed.query)
 with lock:
 if parsed.path=='/fail':faults[query['peer'][0]]=int(query['status'][0])
 if parsed.path=='/release':gates[query['path'][0]].set()
 data={'counts':dict(counts),'active':dict(active),'faults':dict(faults),'held':list(gates)}
 else:
 with lock:
 counts[label]+=1;active[label]+=1;code=faults[label]
 if parsed.path.startswith('/hold/'):gates[parsed.path]=threading.Event()
 if parsed.path.startswith('/hold/'):assert gates[parsed.path].wait(20)
 data={'peer':label,'path':self.path,'connection':self.ident}
 body=json.dumps(data,sort_keys=True).encode();self.send_response(code)
 self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(body)))
 self.end_headers();self.wfile.write(body)
 if label!='control':
 with lock:active[label]-=1
for port,label in [(8081,'A'),(8082,'B'),(8083,'control')]:
 server=ThreadingHTTPServer(('0.0.0.0',port),Handler);server.label=label
 threading.Thread(target=server.serve_forever,daemon=True).start()
threading.Event().wait()
'''
from collections import Counter
extra='''
upstream round { server backend:8081; server backend:8082; }
upstream weighted { server backend:8081 weight=2; server backend:8082; }
upstream by_ip { ip_hash; server backend:8081; server backend:8082; }
upstream by_key { hash $arg_key consistent; server backend:8081; server backend:8082; }
add_header X-Upstream $upstream_addr always; add_header X-Peer $remote_addr always;
'''
locations='\n'.join(f'location /{path}/ {{ proxy_pass http://{group}/; }}' for path,group in
 [('round','round'),('weighted','weighted'),('sticky','by_ip'),('key','by_key')])
with lab(config(locations,extra),backend=backend) as (_,request):
 def get(path,headers=None):
 status,h,b=request(path,headers=headers);assert status==200;data=json.loads(b)
 assert h['x-upstream'].endswith(':8081' if data['peer']=='A' else ':8082')
 return data['peer'],h
 results={}
 for mode,expected in [('round',{'A':6,'B':6}),('weighted',{'A':8,'B':4})]:
 chosen=[get('/'+mode+'/item')[0] for _ in range(12)]
 assert dict(Counter(chosen))==expected,chosen;results[mode]={'sequence':chosen,'counts':dict(Counter(chosen))}
 sticky=[get('/sticky/item',{'X-Forwarded-For':'192.0.2.'+str(i)}) for i in range(1,9)]
 assert len({r[0] for r in sticky})==len({r[1]['x-peer'] for r in sticky})==1
 results['ip_hash']={'peers':[r[0] for r in sticky],'socket_peer':sticky[0][1]['x-peer']}
 groups={}
 for key in ['alpha','beta','gamma','delta','epsilon','zeta']:
 pair=[get('/key/item?key='+key)[0] for _ in range(2)];assert pair[0]==pair[1];groups[key]=pair[0]
 assert set(groups.values())=={'A','B'},groups;results['consistent_key_hash']=groups
 print(json.dumps(results,sort_keys=True))

对同权轮询组顺序发送十二次请求，A、B 各返回六次，本次受控运行中两者交替出现。每个响应的后端标记都会与 nginx 上游地址头中的端口对应检查，因此观察的是实际选中节点，而不是从客户端连接 nginx 的地址推测分布。即使所有请求都经过同一入口，也能明确区分最终由哪个后端回答。

A 权重设为二、B 设为一后，十二次请求产生八个 A 响应和四个 B 响应。这验证了健康节点、顺序请求条件下配置的相对份额，不保证任意流量前缀、包含重试的请求集合，或者存在不可用节点的集群都恰好保持相同比例。衡量权重时应写明节点资格与观察窗口，否则单个小样本容易被过度解释。

IP 哈希组收到来自同一真实套接字对端的八个请求。请求中伪造的 X-Forwarded-For 不断变化，但所有响应仍来自同一后端。这里没有通过 real-IP 信任配置把不可信头转换成客户端地址；观察到的套接字对端字段也保持不变，从而明确本次方法实际使用哪个身份，而不是把声明的转发地址当成已验证来源。

另一个一致性哈希组使用公开查询 key。六个 key 各请求两次，同一 key 的两次访问选择同一后端，所选 key 合计覆盖两个节点。这检查的是当前成员集合下的稳定落点，没有测试成员变更，也没有证明任意客户端可控 key 已经是经过认证的用户身份。稳定映射与身份可信是不同要求。

让方法匹配工作负载及其身份

相近且相互独立的请求，可以使用加权轮询表达简单相对分布。连接占用时间差异较大时，最少连接可以绕开活动连接更多的节点，但仍受自身指标局限约束。需要亲和时，应选择稳定且合适的 key，并明确落点变化后如何处理。路由粘性不能替代复制、共享状态或明确的会话丢失策略，尤其不能当成节点故障后的数据恢复机制。

nginx IP 哈希使用 IPv4 地址的前三个字节，或完整 IPv6 地址。这个文档规定的粒度会影响分布估计，并不总是对完整地址哈希、让每个 IPv4 主机都有独立结果。代理地址处理和 NAT 还会继续改变均衡器看到多少种身份。因此，评估亲和分布之前，应先检查实际进入算法的地址与其粒度。

最后，要把选择策略与节点资格、重试和各节点响应行为一起评估。比较上游尝试地址、耗时与返回内容，而不是看到某个节点慢就断定算法选错。更换方法可以重新分配工作，却不会修复损坏后端，也不能让不安全请求变得适合在另一台机器重试。观测必须能解释真实调用路径，而不仅是一张总请求数图表。

来源

nginx upstream module，权重、ip_hash、一致性 key 哈希与节点选择，已核验 2026-10-15。
nginx HTTP load balancing guide，轮询、最少连接、亲和性与被动失败处理，已核验 2026-10-15。
nginx proxy module，上游转发与重试条件，已核验 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。

proxy_pass 既选择上游，也映射请求 URI

Fri, 02 Apr 2027 00:00:00 +0000

nginx proxy_pass 选择上游目标，也影响实际发送的请求 URI。关键区别是指令是否包含 URI 部分，而不只是文本末尾有没有斜杠。在普通前缀 location 中，字面目标 URI 会替换匹配到的规范化前缀；仅含地址的目标，在请求没有被重写时，可以传递原始请求 URI。理解这两个分支，才能准确预测后端看到的路径。

坏掉的样子

应用只处理 /users，代理却转发 /api/users，即使网络连接成功，也可能得到 404。相反，应用期待公共前缀，而代理把它移除，也会出现错误。只比较客户端状态和上游可达性，无法定位这类问题；需要检查后端真正收到的方法、路径、查询和主机名。成功建立连接并不等于协议内容符合应用契约。

斜杠边界属于字面替换的一部分。以 /v1 结尾的目标仍然包含 URI，所以在 /join/item 中替换 /join/ 后会得到 /v1item，不会因为目标没有末尾斜杠就保留原路径。按被替换前缀和剩余后缀推演，比“有没有末尾斜杠”这句通用口诀更准确，也能解释多段内部路径的映射。

变量会引入另一条文档规定的分支。变量提供的代理 URL 包含 URI 时，使用的是给定 URI，而不是普通字面前缀替换规则。正则和命名 location 也没有同样明确的前缀边界。在普通前缀中工作的配置，不能不检查契约就直接复制到这些上下文，否则语法或运行行为都可能发生变化。

快速验证

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

使用宿主 Python、Docker，以及固定 nginx 和 Python 镜像运行脚本。实测为 Linux arm64 上的 nginx 1.28.0、Python 3.11.16、Docker 29.3.1。它启动真正回显请求字段的 HTTP 后端，验证 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_text(content)
 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()
 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'

backend=r'''from http.server import BaseHTTPRequestHandler,HTTPServer
import json
class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 body=self.rfile.read(int(self.headers.get('Content-Length','0')))
 document={'path':self.path,'method':self.command,'body':body.decode(),'headers':{key:self.headers.get(key) for key in ['Host','X-Forwarded-For','X-Real-IP','X-Forwarded-Proto','X-Forwarded-Host']}}
 data=json.dumps(document).encode()
 self.send_response(200);self.send_header('Content-Type','application/json');self.send_header('Content-Length',str(len(data)));self.send_header('X-Backend-Info','fixture-node');self.end_headers();self.wfile.write(data)
 do_POST=do_GET
 def log_message(self,*args):pass
HTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''

locations=r'''
location /keep/ { proxy_pass http://backend:8081; }
location /strip/ { proxy_pass http://backend:8081/; }
location /replace/ { proxy_pass http://backend:8081/v1/; }
location /join/ { proxy_pass http://backend:8081/v1; }
location /variable/ { set $destination "http://fixture_pool/fixed?chosen=1"; proxy_pass $destination; }
'''
invalid=config(r'location ~ ^/bad/ { proxy_pass http://backend:8081/replacement/; }')
with lab(config(locations,'upstream fixture_pool { server backend:8081; }'),{'invalid.conf':invalid},backend) as (container,request):
 cases={'/keep/item?x=1':'/keep/item?x=1','/strip/item?x=1':'/item?x=1','/replace/item?x=1':'/v1/item?x=1','/join/item?x=1':'/v1item?x=1','/keep/a%2Fb?x=1':'/keep/a%2Fb?x=1','/strip/a%2Fb?x=1':'/a/b?x=1','/variable/item?original=1':'/fixed?chosen=1'}
 for path,expected in cases.items():
 status,headers,body=request(path);assert status==200 and json.loads(body)['path']==expected,(path,status,body)
 invalid_result=docker('exec',container,'nginx','-t','-c','/srv/invalid.conf',check=False)
 assert invalid_result.returncode!=0 and 'cannot have URI part in location given by regular expression' in invalid_result.stderr
 print('no URI preserves the original path; a literal URI replaces the normalized matching prefix, including its slash boundaries')
 print('a variable-supplied URI is used as specified; regex-location URI replacement is rejected by nginx -t')

/keep/ 中仅含地址的目标，把 /keep/item?x=1 原样转发。/strip/ 中以 / 作为目标 URI，则转发 /item?x=1。这两个字面示例都保留查询参数。证据来自后端 JSON 响应，而不是根据 nginx 处理前的公共 URL 猜测。回显字段让代理转换直接可见，也便于把路径错误与连接失败分开。

/replace/ 把前缀映射为 /v1/，所以 /replace/item?x=1 变成 /v1/item?x=1。/join/ 目标故意少一个分隔斜杠，结果为 /v1item?x=1。两个请求都成功到达后端，但路径不同。这说明 TCP 或 HTTP 成功不能证明路由映射正确，后端如果存在宽泛默认路由，还可能把错误进一步隐藏起来。

编码分隔符揭示规范化边界。仅含地址时，/keep/a%2Fb?x=1 仍以编码形式到达后端；通过规范化前缀替换，/strip/a%2Fb?x=1 则变成 /a/b?x=1。这会改变应用划分路径段的方式。当编码标识符或访问边界依赖这些分隔符时，需要让代理和应用的路径解释保持一致，并用实际字节请求验证。

变量示例引用预先定义的上游组，并提供 /fixed?chosen=1 作为目标 URI。请求 /variable/item?original=1 最终恰好到达这个固定 URI，原后缀和查询不会自动追加。使用已知上游组，也让这个实验与任意逐请求主机名解析及其 resolver 要求区分开，不把不同目标选择方式混成一个行为结论。

第二份配置故意在正则 location 中使用带 URI 部分的代理目标，nginx -t 会报告文档规定的 URI 限制并拒绝配置。实验不会用这个无效文件替换正在工作的配置。因此，除了成功路径，还验证了真实配置失败，而不是把所有错误都归结成运行后才出现的后端 404。

把每条公共到后端的映射作为契约

对每个代理 location，写清公共前缀、是否有替换 URI，以及预期后端路径和查询。测试应包含边界斜杠和编码形式。如果代理前有 rewrite 改变 URI，也要重新检查仅地址形式：转发原始请求取决于是否仍在处理原始 URI，不是对所有重写请求都成立的无条件承诺。配置组合会改变分支，不能只孤立看一行。

目标选择应限制在预期后端内。来自不可信请求数据的变量，不应成为任意访问其他主机的权限。命名上游组、显式映射和拒绝行为，应依据应用真实路由需求配置，不能默默接受未知目的地。路径转换正确与目标选择安全，是相关但不同的检查项，需要分别有证据。

转发头、连接复用、超时和上游 TLS 应按各自契约配置。resolver 不是能让变量目标或 keepalive 一概正确的开关。应分别测试这些行为，并保留后端观察来证明 URI 映射，避免用未经测量的性能或解析假设替代本来可以直接验证的请求内容。

来源

nginx proxy_pass reference，URI 替换、原始请求转发、变量目标与正则限制，已核验 2026-10-15。
nginx core location matching，代理处理前的规范化前缀选择，已核验 2026-10-15。
nginx upstream module，命名上游组与后端选择，已核验 2026-10-15。

上游 keepalive 缓存空闲连接，不限制活动容量

Mon, 15 Mar 2027 00:00:00 +0000

nginx 上游 keepalive 缓存会保留符合条件的空闲后端连接，供后续请求复用。在本次配置中，keepalive 2 允许每个 worker 为该上游缓存保留两条空闲连接，并不把 worker 的活动后端连接限制为两条。复用可以减少重复建立连接的开销，却不会自动施加应用并发预算，也不能保证每个请求的延迟都下降。空闲保留与活动容量需要分别理解。

坏掉的样子

把空闲缓存大小误当成连接上限，会让后端同时承受的工作量超过预期。忙碌 worker 可以继续新建活动连接，而保留的空闲缓存仍很小。存在多个 worker 时，各自的空闲缓存也需要计入资源。将 nginx 配置与后端真实连接容量比较时，应分别统计活动与空闲资源，不能只拿一个 keepalive 数字作为全部连接预算。

复用要求协议交换本身可以继续使用。在这个 nginx 1.28.0 HTTP 示例中，上游 HTTP/1.1 和清除默认 Connection: close 都是显式配置。仅设置 Host 并不能建立持久连接。后端仍可能主动关闭连接，不完整或分帧错误的消息，也不能仅因为配置了缓存，就被当成干净可复用的交换。连接是否适合归还空闲缓存，需要实际通信满足条件。

客户端持久连接属于另一组连接关系。新的客户端连接可以使用之前缓存的上游连接；长时间存在的客户端也可能触发多条后端连接。假设两者生命周期总是一致，会产生误导性测量。建立连接的节省也取决于后端使用明文 HTTP 还是 TLS；本次 nginx 后面采用明文 HTTP，因此没有把 TLS 握手节省写成已测结果。

快速验证

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

将脚本保存为 check-upstream-keepalive.py，准备 Python、Docker 和固定镜像后执行。实验使用单个 nginx 1.28.0 worker，以及专用网络里的 Python HTTP/1.1 后端。后端为每条接收连接分配身份，每个响应都提供明确长度。客户端通过宿主回环进入 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'
from concurrent.futures import ThreadPoolExecutor
backend=r'''
from http.server import BaseHTTPRequestHandler,ThreadingHTTPServer
import itertools,json,threading
ids=itertools.count(1);lock=threading.Lock();opened=set();active=set();release=threading.Event()
class Handler(BaseHTTPRequestHandler):
 protocol_version='HTTP/1.1'
 def setup(self):
 super().setup();self.ident=next(ids)
 with lock:opened.add(self.ident)
 def finish(self):
 try:super().finish()
 finally:
 with lock:opened.discard(self.ident)
 def log_message(self,*args):pass
 def do_GET(self):
 if self.path=='/hold':
 with lock:active.add(self.ident)
 assert release.wait(15)
 with lock:active.remove(self.ident)
 elif self.path=='/release':release.set()
 with lock:data=json.dumps({'connection':self.ident,'active':sorted(active),'other_open':sorted(opened-{self.ident}),
 'host':self.headers.get('Host'),'connection_header':self.headers.get('Connection')}).encode()
 self.send_response(200);self.send_header('Content-Length',str(len(data)));self.end_headers();self.wfile.write(data)
ThreadingHTTPServer(('0.0.0.0',8081),Handler).serve_forever()
'''
locations='''
location /reuse/ { proxy_http_version 1.1; proxy_set_header Connection ""; proxy_pass http://pool/; }
location /close/ { proxy_http_version 1.1; proxy_set_header Connection close; proxy_pass http://pool/; }
location /host-only/ { proxy_http_version 1.1; proxy_set_header Host service.example; proxy_pass http://pool/; }
location /control/ { proxy_set_header Connection close; proxy_pass http://backend:8081/; }
'''
extra='upstream pool { server backend:8081; keepalive 2; keepalive_timeout 30s; }'
with lab(config(locations,extra),backend=backend) as (_,request):
 def get(path):
 status,_,body=request(path);assert status==200;return json.loads(body)
 results={}
 for mode in ['reuse','close','host-only']:
 first=get('/'+mode+'/id');second=get('/'+mode+'/id')
 assert (first['connection']==second['connection'])==(mode=='reuse')
 if mode=='host-only':assert first['host']=='service.example' and first['connection_header']=='close'
 results[mode]={'connections':[first['connection'],second['connection']],'host':first['host'],'connection_header':first['connection_header']}
 with ThreadPoolExecutor(max_workers=4) as pool:
 futures=[pool.submit(get,'/reuse/hold') for _ in range(4)]
 wait(lambda:len(get('/control/state')['active'])==4)
 active=get('/control/state')['active'];assert len(set(active))==4
 get('/control/release');replies=[f.result(timeout=10) for f in futures]
 assert len({r['connection'] for r in replies})==4
 wait(lambda:len(get('/control/state')['other_open'])==2)
 results['concurrent_active']=active;results['idle_after_burst']=get('/control/state')['other_open']
 print(json.dumps(results,sort_keys=True))

连续两次 /reuse/id 返回相同后端连接身份。客户端辅助函数每次请求都新建并关闭自己的 HTTP 连接，因此观察到的是跨不同下游连接的上游复用。该 location 显式使用上游 HTTP/1.1，并且不发送 Connection 头。每个响应完整读完后，后端交换才具备进入空闲状态的条件，不能在正文尚未消费完时仅凭状态成功判断连接可复用。

/close/id 对照发送 Connection: close，连续请求得到不同后端连接身份。/host-only/id 对照修改 Host，却保留关闭行为，响应同样使用不同连接。这些比较说明：即使所有路径连接同一个应用，用于路由的头也不能替代正确的持久连接设置。观察请求头和连接身份，比只看两次请求都成功更有解释力。

接着，四个客户端请求由后端故意保持未完成的响应。控制端等到后端报告四个活动连接身份后，才放行任何响应。这直接展示 keepalive 2 下仍有四条并发上游连接，不是根据耗时猜测并发，也不是数四个可能顺序完成的请求。受控等待使活动连接数量成为可以直接检查的中间状态。

放行后，四个响应全部完成。实验随后观察到恰好两条剩余空闲后端连接，计数排除了用于查询状态的短期控制连接。最终保留哪些身份会随完成顺序变化，断言关心的是数量。这样就能区分配置规定的空闲保留上限，与突发期间实际使用的更大活动连接集合，避免把两种阶段混成一个总上限。

让复用设置匹配后端行为

应结合连接建立成本、预期再次使用概率、后端限制和 nginx worker 数量确定空闲保留规模。连接即使没有承载请求，保留期间也会占用资源。过大的缓存可能挤占新请求可用连接，过小的缓存则可能反复丢弃马上就会复用的连接。选择规模需要真实访问分布和后端预算，而不是一律把值调大。

请求次数、空闲时间和连接总寿命控制，会因为不同原因回收持久连接。不要看到重连就同时提高所有限制。应先观察后端主动关闭、有效配置、响应分帧完成情况，以及真实连接身份。本次空闲超时设为三十秒，短暂突发没有测量长期连接老化，也没有测量 TLS 会话行为，因此不能据此推断那些不同机制的效果。

如果目标是限制后端工作量，应采用真实并发或准入策略；keepalive 负责复用策略。示例明确选择协议和缓存设置，因为滚动文档还包含较新 nginx 的默认值与功能。应用时要遵循实际部署版本的语义，同时验证连续复用和并发突发，不能认为一次重复请求成功复用，就已经证明容量边界受到控制。

来源

nginx upstream module，空闲连接缓存、worker 范围与 keepalive 限制，已核验 2026-10-15。
nginx 1.28.0 upstream keepalive source，被测版本的空闲缓存与连接复用实现，已核验 2026-10-15。
RFC 9112 HTTP/1.1，持久连接、消息分帧与 Connection close，已核验 2026-10-15。

Nginx · XB 现场笔记

微缓存短暂复用新鲜条目，并显式合并并发未命中

坏掉的样子

快速验证

分别决定新鲜度与过载行为

延伸阅读

来源

nginx 验证器是否可靠，取决于表示身份是否准确

坏掉的样子

快速验证

让部署保持验证器契约

延伸阅读

来源

HTTP3 走 UDP，HTTP2 仍走 TCP 兜底

两种传输，一个端口号

Alt-Svc 是客户端得知的方式

0-RTT 与连接迁移是两处锋利的边缘

坏掉的样子

快速验证

来源

SNI 让一个 IP 承载多个 HTTPS 站点

名字最先报出

用 server_name 匹配

把缺省回退控制好

坏掉的样子

快速验证

延伸阅读

来源

gzip、HTTP/2 与 Brotli 需要分别验证

坏掉的样子

快速验证

先确认能力，再比较性能

延伸阅读

来源

先决定让 nginx 跳转客户端，还是在内部重写

坏掉的样子

快速验证

测试客户端真正收到的转换

延伸阅读

来源

nginx 前缀在匹配结束前只是候选配置

坏掉的样子

快速验证

审阅所选处理器及其后续转换

来源

nginx 突发容量决定哪些请求等待、哪些被拒绝

坏掉的样子

快速验证

让等待策略匹配端点需求

来源

nginx 选择第一个匹配正则，不会计算通用具体程度分数

坏掉的样子

快速验证

让重叠在审阅中可见

来源

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

坏掉的样子

快速验证

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

延伸阅读

来源

显式启用 gzip，再验证协商与解码后的字节

坏掉的样子

快速验证

用有代表性的响应调整策略

延伸阅读

来源

请求限流保护的是 key 所命名的预算

坏掉的样子

快速验证

一起定义身份、范围和观测方式

来源

反向代理需要明确的请求头信任边界

坏掉的样子

快速验证

连接网络访问规则与头部解释

延伸阅读

来源

nginx 匹配规范化路径，并可能再次选择 location

坏掉的样子