限流 · XB 现场笔记

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。

令牌桶限制准入并允许突发

Wed, 01 Dec 2027 00:00:00 +0000

令牌桶限制获准进入的工作量，同时允许积累的额度在短时间内集中使用。它不会自动把请求均匀隔开，不保证成功完成的吞吐，也不限制仍在执行的操作数量；这些分别属于调度和容量问题。桶的两个参数描述的是预算，不是服务一定能够履行的处理能力承诺。

先补充额度，再扣除工作成本

设桶容量 B 为最多能保存的令牌数，回填速率 r 为每秒新增令牌数。每次请求到来，先将额度更新为 min(B, 上次额度 + r × 经过时间)。只有工作成本不超过当前额度才准入，然后扣除成本。本文采用的严格规则下，被拒绝的工作不消耗令牌。

这种计算可以在请求到达时按需进行，不需要后台定时器不断实际投放令牌。长时间空闲也不能积累无限额度，因为容量会截断回填结果。初始额度是一项策略选择：本例从满桶开始，因此允许立即突发；从空桶开始则会得到不同的初始行为，不能漏写这个条件。

突发额度不是峰值速率

对于这个理想严格模型，在长度为 t 的时间区间内，获准工作的总成本不超过 B + r × t。时间越长，突发项的相对影响越小。这不意味着每个一秒窗口都最多允许 r 个请求，也没有额外给出一个独立的瞬时峰值速率上限。

例如容量为三、每秒回填二时，三个单位成本请求可以在同一时刻全部通过，第四个被拒绝；半秒之后又有一枚令牌可用。如果已获准的工作必须均匀离开入口，还需要实际调度器、有界等待队列或其他节奏控制，不能指望令牌桶自动将同时到达的请求排成匀速流。

准入速率也不等于执行并发量。慢请求尚未结束时，令牌仍会继续回填，允许更多工作进入。需要通过合适的并发限制和超时策略保护工作线程、数据库等稀缺资源。同样，已经准入的请求仍可能在下游失败，所以回填速率不能被写成保证成功完成的吞吐。

预算单位和作用范围要一致

一枚令牌不一定对应一个请求，也可以用加权成本代表字节或预计工作量，但容量与回填速率必须使用相同单位。一个成本超过 B 的请求，无论等待多久都装不进这个严格模型的桶。应明确处理这种情况，而不是给出一个实际上永远不能兑现的重试时间。

还要明确预算按谁区分、由谁持有。四个互相独立的满桶，每个保存三枚令牌，可以同时允许十二个请求；它们不是一个全局三令牌桶。共享限流器必须把回填、比较和扣减协调成一次原子决定，仅共享一个计数器而分开执行这些步骤，并不足以保证配额正确。

本地回填应依据经过时间的时钟，不能让墙上时钟校准凭空增加额度，或使记账时间倒退。Python 的单调时钟适合比较两次读取的差值，但其参考原点不是可以在无关机器之间交换的通用时间戳。分布式时钟和状态归属仍需要自己的明确契约。

坏掉的样子

即使长期速率看起来保守，满桶释放的一次突发仍可能压垮脆弱的下游。无界等待队列会把超额需求转化为内存增长与延迟；直接拒绝和延迟整形是两种不同结果，接口应说明调用者会得到哪一种，不能把所有行为都笼统叫作“平滑”。

应一起观察准入成本、拒绝成本、排队、并发量和下游延迟。重试需要遵守限流策略，而不是立即重新制造被拒绝的负载。按尝试工作计费还是按完成工作计费，也是需要明确的选择；失败后退还令牌会改变模型，并引入额外记账要求，不能悄悄当成同一套公式。

托管产品的限制还可能弱于理想算法。Amazon API Gateway 明确说明限流和配额是尽力而为的目标，可能被超过。因此，不能把这里的数学上界宣传成该服务已经验证的硬保证、费用上限，或者任何未经测试部署的严格承诺。

快速验证

保存为 bucket_check.py，用 Python 3.10 以上版本执行 python3 bucket_check.py。本例已在 Python 3.14.4 上运行。标准库 Fraction 与注入的非递减时间戳让边界计算保持精确，不依赖真实等待。这是单线程准入模型，不是网络限流服务或分布式存储实现。

from fractions import Fraction


class Bucket:
 def __init__(self, capacity, rate):
 assert capacity > 0 and rate > 0
 self.capacity, self.rate = capacity, rate
 self.tokens, self.updated = Fraction(capacity), Fraction(0)

 def take(self, now, cost=1):
 assert now >= self.updated and cost > 0
 self.tokens = min(self.capacity, self.tokens + (now - self.updated) * self.rate)
 self.updated = now
 if self.tokens < cost:
 return False
 self.tokens -= cost
 return True


bucket = Bucket(capacity=3, rate=2)
events = ([(Fraction(0), 1)] * 4 + [(Fraction(1, 4), 1), (Fraction(1, 2), 1),
 (Fraction(3, 2), 2)] + [(Fraction(100), 1)] * 4)
results = [(now, cost, bucket.take(now, cost)) for now, cost in events]
assert [allowed for _, _, allowed in results] == [
 True, True, True, False, False, True, True, True, True, True, False,
]
for now, cost, allowed in results:
 print(f"t={str(now):>3} cost={cost} {'allow' if allowed else 'deny'}")
assert bucket.tokens == 0
marks = sorted({now for now, _ in events})
for start in marks:
 for end in marks:
 if end >= start:
 consumed = sum(cost for now, cost, allowed in results if allowed and start <= now <= end)
 assert consumed <= bucket.capacity + bucket.rate * (end - start)
print("every event-bounded interval obeys admitted cost <= B + r * elapsed")

assert not bucket.take(Fraction(200), cost=4)
assert bucket.tokens == 3
assert bucket.take(Fraction(200), cost=3)
print("cost above capacity never fits; rejection does not consume tokens")

workers = [Bucket(capacity=3, rate=2) for _ in range(4)]
local_admitted = sum(worker.take(Fraction(0)) for worker in workers for _ in range(4))
shared = Bucket(capacity=3, rate=2)
shared_admitted = sum(shared.take(Fraction(0)) for _ in range(16))
assert local_admitted == 12 and shared_admitted == 3
print("four independent full buckets admit", local_admitted, "at once; one shared bucket admits", shared_admitted)

轨迹先允许三个同时到达的请求，拒绝第四个和四分之一秒时的请求；半秒时允许一个，随后在一秒半时允许成本为二的工作。经过很长空闲之后，也只能再放行三枚令牌对应的突发。断言检查所有以事件时间为端点的区间，确认准入成本符合预算上界。

超出桶容量的请求被拒绝，但不会花掉已经积累的额度。最后，四个独立桶同时允许十二个请求，而单个共享的顺序模型只允许三个。这能说明作用范围如何改变配额，却不是对分布式并发扣减正确性的验证，不能把顺序执行的结果当成消除了竞争条件的证据。

本实验没有测试并发竞争、真实时钟调整、队列调度、云平台限流、网络分区或生产性能。它验证的是严格模型的额度更新、分数时间边界和作用范围差异；落地时仍需针对实际状态存储、客户端行为与运行环境重新验证。

来源

RFC 3290，附录 A 的令牌桶预算上界与严格符合性计算，已核验 2026-09-08。
Amazon API Gateway 限流，请求预算、突发与尽力而为限制，已核验 2026-09-08。
Python time，单调经过时间时钟及参考原点边界，已核验 2026-09-08。

请求限流保护的是 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。

Retry-After 告诉你何时再试

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

Retry-After 告诉客户端，在发起后续请求之前应当等待多久。它是调度信号，不证明下一次请求一定成功，也不证明重放原操作是安全的。客户端仍然需要截止期限、尝试次数政策，以及哪些操作可以重试的判断，不能把这些责任都交给一个响应头。

结合响应语境解释字段值

RFC 9110 允许非负十进制整数秒数，或者 HTTP 日期。秒数从收到响应之后开始计算，不是从发出原请求时算起；日期则表示一个绝对 UTC 时刻，因此正确解释它依赖客户端墙上时钟足够准确，不能把两个形式都当成“从请求开始算多久”。

发送方必须使用首选的 IMF-fixdate 格式。解析 HTTP 日期的接收方还必须接受两种旧格式，其中旧 RFC 850 格式的两位年份需要遵守五十年解释规则。负数、小数秒和任意文字，都不是合法的 delay-seconds；零和已经过去的日期，则不要求增加服务器指定的等待时间。

配合 503 时，该字段估计服务还会对客户端不可用多久；配合 3xx 响应时，它要求在发送重定向请求之前至少等待相应时间。RFC 6585 另行允许 429 携带 Retry-After，但这里是可选字段，不是每一条限流响应都必须包含的内容。

尊重等待时间，但不无限等待

一个合法等待值可能长于调用方剩余期限。客户端可以停止重试并报告失败，或者在另有授权的流程中安排后续处理；不能只是为了符合本地上限，就缩短服务器要求的等待，然后提前发起请求。很长的值并不自动等于格式错误，也可能是真实的维护安排。

把绝对日期换算成等待时长后，执行调度和经过时间记账应使用单调时钟。真正开始下一次尝试之前，还应重新检查期限，并为这次请求本身保留完成时间。时钟偏差、响应传输和调度延迟，都说明计算出的计划时间与实际请求时间不是同一份证据。

如果字段缺失或无法使用，有界客户端政策可以采用自己的退避规则。但那是客户端的选择，不是服务器给出的恢复估计。必须明确最多尝试几次、总共允许耗费多久，避免一个可选字段让暂时失败变成没有终点的重试循环。

相同等待值仍可能让调用者同时回来

如果成千上万的客户端几乎同时收到相同等待值，它们仍可能在同一个时刻返回。Retry-After 本身不会把这些请求自动摊开到恢复窗口。可以在尊重要求的等待后增加非负抖动，或者用其他不早于该边界的调度方式，但不能向前减掉等待来制造错峰。

组合本地退避和服务器提示时，需要同时保留两者约束。示例取本地退避与解析出的等待值中较大者，再添加正向抖动。注入的偏移量展示的是调度关系，不是实际分布式流量的测量结果，也不是对某个生产环境抖动范围的推荐。

坏掉的样子

当原请求结果未知时，盲目重放写操作可能重复产生副作用。429、503 和 Retry-After 都不会赋予操作幂等保证；重复非幂等工作之前，需要依据应用自己的重试契约，包括操作标识或去重规则，不能只检查响应头是否存在。

不同客户端库的自动重试和重定向行为也不相同。应验证真实客户端会处理哪些状态、方法和字段。实验政策只对 429 或 503 后的 GET、HEAD 做重试计划，明确不跟随重定向、不重放 POST。这是一个有界示例政策，不是 HTTP 所有幂等方法的完整名单。

非法值、巨大等待、过时日期、耗尽的截止期限和次数上限，都应进入测试。应观察真正的请求尝试与等待，而不是认为配置了响应头就代表客户端已经遵守。服务器也可能在估计时间之后仍不可用，所以重试流程需要一个清楚的终止结果。

快速验证

保存为 retry_check.py，用 Python 3.10 以上版本执行 python3 retry_check.py。此前记录使用 Python 3.14.4，本轮没有重跑；仅用标准库。代码向自己创建的回环 HTTP 服务发送真实请求，使用固定测试日期和注入时钟，结束后停止服务；不会实际等待到下一次重试，也不访问外部服务。

from datetime import datetime, timedelta, timezone
from email.utils import format_datetime, parsedate_tz
from http.client import HTTPConnection
from http.server import BaseHTTPRequestHandler, HTTPServer
import re
from threading import Thread


UTC = timezone.utc
REFERENCE = datetime(2026, 9, 8, 12, 0, 0, tzinfo=UTC)


def delay_seconds(value, received_wall):
 if value is None:
 return None
 value = value.strip(" \t")
 if re.fullmatch(r"[0-9]+", value):
 # Huge decimal values become infinity and fail the bounded retry budget.
 return float(value)
 parts = parsedate_tz(value)
 if parts is None:
 return None
 year, month, day, hour, minute, second = parts[:6]
 old_date = re.fullmatch(r"[A-Za-z]+, [0-9]{2}-[A-Za-z]{3}-([0-9]{2}) [0-9:]{8} GMT", value)
 if old_date:
 now = datetime.fromtimestamp(received_wall, UTC)
 year = now.year // 100 * 100 + int(old_date[1])
 if (year, month, day, hour, minute, second) > (
 now.year + 50, now.month, now.day, now.hour, now.minute, now.second
 ):
 year -= 100
 if not 0 <= second <= 60:
 return None
 try:
 stamp = datetime(year, month, day, hour, minute, min(second, 59), tzinfo=UTC)
 stamp += timedelta(seconds=(second == 60) - parts[9])
 except (ValueError, OverflowError):
 return None
 return max(0.0, stamp.timestamp() - received_wall)


def retry_at(status, method, value, received_wall, monotonic_now, remaining, attempt, jitter=0.25):
 assert attempt >= 1 and jitter >= 0
 if status not in (429, 503) or method not in ("GET", "HEAD") or attempt >= 3:
 return None
 server_delay = delay_seconds(value, received_wall)
 wait = max(server_delay or 0.0, 2 ** (attempt - 1)) + jitter
 if wait >= remaining:
 return None
 return monotonic_now + wait


wall = REFERENCE.timestamp()
for value in ("Tue, 08 Sep 2026 12:00:07 GMT", "Tuesday, 08-Sep-26 12:00:07 GMT",
 "Tue Sep 8 12:00:07 2026"):
 assert delay_seconds(value, wall) == 7
assert delay_seconds("Sunday, 06-Nov-94 08:49:37 GMT", wall) == 0
assert delay_seconds("Monday, 08-Sep-70 12:00:00 GMT", wall) == (
 datetime(2070, 9, 8, 12, tzinfo=UTC).timestamp() - wall
)
assert delay_seconds("Sat, 31 Dec 2016 23:59:60 GMT",
 datetime(2016, 12, 31, 23, 59, 59, tzinfo=UTC).timestamp()) == 1
for invalid in ("-1", "1.5", "later", "", "٣", "Tue, 31 Feb 2026 12:00:00 GMT"):
 assert delay_seconds(invalid, wall) is None
assert delay_seconds(" 0003\t", wall) == 3
assert retry_at(503, "GET", "9" * 5000, wall, 100, 10, 1) is None
assert retry_at(503, "GET", "3", wall, 100, 2, 1) is None
assert retry_at(503, "POST", "3", wall, 100, 10, 1) is None
assert retry_at(503, "GET", "3", wall, 100, 10, 3) is None
print("both delay forms, obsolete dates, year interpretation, and invalid values are checked")
print("an oversized wait, exhausted deadline, POST, or attempt cap stops this retry policy")

cases = {
 "/seconds": (429, "3"),
 "/date": (503, format_datetime(REFERENCE + timedelta(seconds=7), usegmt=True)),
 "/invalid": (503, "later"),
 "/missing": (503, None),
 "/redirect": (307, "3"),
 "/ready": (200, None),
}
visited = []


class Handler(BaseHTTPRequestHandler):
 def do_GET(self):
 visited.append(self.path)
 status, value = cases.get(self.path, (404, None))
 self.send_response_only(status)
 self.send_header("Date", format_datetime(REFERENCE, usegmt=True))
 if value is not None:
 self.send_header("Retry-After", value)
 if status == 307:
 self.send_header("Location", "/ready")
 self.send_header("Content-Length", "0")
 self.end_headers()

 def log_message(self, *_):
 pass


with HTTPServer(("127.0.0.1", 0), Handler) as server:
 thread = Thread(target=server.serve_forever, kwargs={"poll_interval": 0.05})
 thread.start()
 try:
 for route, expected in (("/seconds", 103.25), ("/date", 107.25),
 ("/invalid", 101.25), ("/missing", 101.25), ("/redirect", None)):
 client = HTTPConnection(*server.server_address, timeout=2)
 try:
 client.request("GET", route)
 response = client.getresponse()
 response.read()
 planned = retry_at(response.status, "GET", response.getheader("Retry-After"),
 wall, 100, 10, 1)
 assert planned == expected
 print(route, "status", response.status, "planned monotonic time", planned)
 finally:
 client.close()
 assert "/ready" not in visited
 finally:
 server.shutdown()
 thread.join(timeout=2)
 assert not thread.is_alive()

same_delay = [retry_at(429, "GET", "3", wall, 100, 10, 1, jitter=0) for _ in range(4)]
spread = [retry_at(429, "GET", "3", wall, 100, 10, 1, jitter=j) for j in (0.1, 0.2, 0.3, 0.4)]
assert same_delay == [103] * 4
assert len(set(spread)) == 4 and min(spread) > 103
print("identical server delays synchronize plans; injected positive jitter spreads them:", spread)

解析检查覆盖列出的秒数、日期、旧格式、年份解释、闰秒和非法输入，但 email.utils 还接受 HTTP 日期语法之外的输入。因此这是宽松的调度演示，不是严格的 RFC 语法验证器；生产环境需要明确自己的接收和拒绝政策。有界政策会放弃超过剩余期限的等待、POST 重放，以及达到次数上限后的再次尝试。日期和时钟是明确设定的测试数据，并没有修改机器时间，也不代表运行当时的真实 UTC 时刻。

本地 429 返回三秒等待时，从注入的单调时间一百计算出 103.25 的计划时间；日期形式的 503 得到 107.25。缺失或非法字段使用已经声明的本地退避，重定向则不会被自动跟随。四个相同延迟产生四个 103 的计划，注入正向抖动后得到 103.1 到 103.4，展示的是可以验证的计划差异。

这些是响应与调度决定测试，不是实际按时重试的验收。真实时钟校准、网络分区、代理行为、生产抖动分布和业务操作去重仍未测试。落地时应观察最终发出的请求，不能把一组正确的计算时间，直接当成客户端已经在复杂网络中按时重试的证据。

来源

RFC 9110，5.6.7 和 10.2.3 节定义 HTTP 日期和 Retry-After，已核验 2026-10-15。
RFC 6585，429 中可选的 Retry-After，已核验 2026-10-15。
Python 邮件工具，日期解析、UTC 偏移和时间戳格式化，已核验 2026-10-15。

限流需要一个稳定的客户端标识

Thu, 29 Oct 2026 00:00:00 +0000

限流键定义了哪些请求共用一份预算。账号、API 凭据、地址、租户和已认证会话是不同身份，不是“客户端”的几种可互换写法。选错归组方式，可能让无关用户相互挤占额度，也可能让同一份工作只改一个字段，就拿到新的使用机会。

使用政策真正承诺的身份

如果规则是按账号限流，就应从认证结果中取得账号，而不是相信调用方提交的账号请求头或查询参数。仅仅看见一个凭据，并不能证明它有效；认证层必须先验证凭据、解析主体，再让账号级准入决定使用这个结果。限流键的可信程度不能高于它的来源。

按凭据限流也可以是合理的产品契约，但行为与按账号限流不同。轮换凭据或再创建一份凭据，可能得到新的凭据键，却仍属于同一个账号。应先决定这是否应当带来新额度，而不是等出现滥用或投诉后，才发现实现按的身份与产品描述并不一致。

一个账号不一定只对应一个人或一个应用，一个人也可以拥有多个账号。稳定账号键改善的是归组的一致性，并不证明公平，不阻止批量养号，也不限制整个服务的总需求。其他层级的限制应由明确需求支持，不能认为“已经按账号计数”就涵盖所有容量风险。

地址表示的是网络路径

企业 NAT、运营商网络或 VPN 后面的多个账号，可能共用一个公网地址；按 IP 的桶会把它们的流量合在一起。反过来，更换地址的调用方可能进入一个新桶。这两种结果并不说明地址解析错误，而是说明网络地址与业务主体本来就在表示不同对象。

没有已验证账号的公开接口或认证前入口，仍可以用地址级限制保护资源。但应按地址政策评估阈值，包括正常共享网络的流量，不能把它描述成精确的个人限制，也不能假设一个地址规则一定拦得住分散在许多网络上的抓取者。

地址在成为键之前需要语法规范化。同一个 IPv6 地址的不同合法写法，不应创建多份额度。是否按网段聚合，或把特定地址族形式视为同一个对象，是另外的政策选择，需要权衡误伤范围；规范化文本本身并不能替你回答这些业务问题。

转发身份必须有信任边界

随意提交的 Forwarded、X-Forwarded-For 或类似字段，不是客户端来源的证明。RFC 7239 明确指出，客户端和沿途节点都能改变转发信息。是否可信取决于直接连接的对端、配置的代理链，以及这条链如何移除或安全处理用户原先提交的字段。

NGINX 的真实 IP 模块需要明确配置可信来源地址和递归处理规则。“永远取转发字段里的第一个地址”不是适用于所有网络的正确方法。如果代理接收后原样转发了不可信声明，看似稳定的身份键就可能变成由调用者控制的新预算生成器。

下面的实验只模拟一个已经配置的可信代理，它会覆盖字段，并只发送一个 IP 字面值。其他对端提交的替换声明被忽略，来自这个代理的多地址列表则被拒绝。它不是通用代理链解析器，也不是已经部署并验收的 NGINX 配置，不能直接扩大其覆盖范围。

坏掉的样子

键里漏掉租户维度，会合并不同租户中标识相同的账号。按原始 URL 计数，又可能因为查询参数不同，把同一个操作拆成多个桶；如果政策按操作限流，应使用路由解析出的稳定操作身份。直接拼接字符串还可能产生歧义，应在编码中保留各组件边界。

不要把原始 bearer 秘密作为预算键或诊断标签。稳定的内部凭据标识或主体标识通常更合适，日志也仍需要隐私控制。无限创建身份会消耗限流器内存；评估过期或状态淘汰时，还应考虑桶被重置后产生的新额度，不能只看到内存回收这一面。

选定阈值前，应测试共享地址、漫游客户端、凭据轮换、租户隔离和伪造声明等真实身份组合。还要沿数据来源检查所谓“已验证主体”是否真的来自认证结果。如果它本身是从不可信请求直接复制出来的，后面再精巧的字典键也修复不了这个信任错误。

快速验证

保存为 identity_check.py，用 Python 3.10 以上版本执行 python3 identity_check.py。实验已在 Python 3.12.14 上运行，只使用标准库。记录代表已经完成认证和路由解析的测试请求，并不是认证实现；计数器只模拟一个测试窗口，不启动服务，不发送网络请求，也不写文件。

from collections import Counter
from ipaddress import ip_address


def account_key(request):
 # These two fields come from authentication and routing, not request headers.
 tenant, account = request["verified_actor"]
 return ("account", tenant, account, request["operation"])


def admit(counts, key, limit=2):
 if counts[key] >= limit:
 return False
 counts[key] += 1
 return True


alice = {"verified_actor": ("north", "alice"), "operation": "export",
 "peer": "198.51.100.8", "credential_id": "key-a", "claimed_account": "alice"}
bob = {**alice, "verified_actor": ("north", "bob"), "credential_id": "key-b"}
by_ip, by_account = Counter(), Counter()
assert [admit(by_ip, str(ip_address(request["peer"]))) for request in (alice, alice, bob)] == [
 True, True, False,
]
assert [admit(by_account, account_key(request)) for request in (alice, alice, bob)] == [
 True, True, True,
]
print("two accounts behind one address collide in the IP budget, but not the account budget")

roaming = {**alice, "peer": "203.0.113.9", "credential_id": "key-a-rotated"}
assert admit(by_ip, str(ip_address(roaming["peer"])))
assert not admit(by_account, account_key(roaming))
for claim in ("bob", "new-account", "admin"):
 assert account_key({**roaming, "claimed_account": claim}) == account_key(alice)
print("changing address, credential ID, or an untrusted account claim does not reset this account budget")

other_tenant = {**alice, "verified_actor": ("south", "alice")}
other_operation = {**alice, "operation": "thumbnail"}
assert admit(by_account, account_key(other_tenant))
assert admit(by_account, account_key(other_operation))
assert account_key({**alice, "verified_actor": ("a:b", "c")}) != account_key(
 {**alice, "verified_actor": ("a", "b:c")}
)
print("tenant and operation are explicit dimensions; tuple encoding avoids delimiter collisions")

# One configured proxy that overwrites the header with exactly one IP literal.
trusted_proxy = ip_address("192.0.2.10")


def network_key(peer, replacement):
 peer = ip_address(peer)
 return str(ip_address(replacement)) if peer == trusted_proxy else str(peer)


assert network_key("198.51.100.8", "203.0.113.77") == "198.51.100.8"
assert network_key("198.51.100.8", "not-an-address") == "198.51.100.8"
assert network_key("192.0.2.10", "198.51.100.8") == "198.51.100.8"
assert network_key("2001:0db8:0:0::1", "ignored") == network_key("2001:db8::1", "ignored")
try:
 network_key("192.0.2.10", "198.51.100.8, 203.0.113.9")
except ValueError:
 pass
else:
 raise AssertionError("the single-address proxy contract must reject a chain")
print("untrusted peers cannot choose a forwarded identity; equivalent IPv6 text shares one key")
print("the configured one-address proxy contract rejects a multi-address value")

Alice 耗尽地址桶后，同地址的 Bob 也会被阻止；按账号归组则保留 Bob 自己的额度。Alice 更换地址可以得到新 IP 额度，但换地址、轮换凭据标识，或者伪造账号声明，都不会改变这里的账号键。这个结果依赖测试记录中的主体已经可信，不能反过来作为认证正确性的证明。

不同租户与不同操作得到独立键，元组保留组件边界，避免分隔符碰撞。非可信对端不能选择替换地址，同一个 IPv6 地址的等价写法被统一；单代理、单地址契约会拒绝地址列表。真实认证、代理转发、并发计数、分布式配额和生产身份数量都未在本例中验证。

来源

RFC 6585，第四节将身份选择与计数范围交给限流政策定义，已核验 2026-09-08。
RFC 7239，转发字段完整性、可信代理与信息暴露，已核验 2026-09-08。
NGINX 真实 IP 模块，可信替换地址与递归处理，已核验 2026-09-08。

限流是共享预算

Sat, 22 Aug 2026 00:00:00 +0000

限流是一份关于获准工作量的预算，需要明确单位、身份、作用范围和时间规则。只说“五次请求”还不够：要说明是谁的请求、覆盖哪些入口与工作进程、按什么区间计数，以及耗尽后如何处理。即使用了共享计数器，也只有所有相关请求都经过同一个权威准入决定，才能落实共享预算。

先定义政策，再开始计数

一次请求可以消耗一个单位，也可以按预计工作量或字节数加权。按准入尝试、成功执行或退还额度分别记账，必须由契约明确规定，不能在实现中悄悄混用。获得预算只意味着允许继续执行，不保证后续业务操作一定成功，也不等于为成功结果预留了全部资源。

窗口算法并不相同。固定窗口可能在边界附近允许突发，滚动窗口衡量的是另一段区间；令牌桶允许迅速花掉已经积累的额度，并不会自动把请求均匀发出。这些算法本身也不限制仍未结束的慢操作数量，准入速率不能替代执行并发上限。

账号、路由、地域和整个服务的预算分别回答不同问题。剩余额度只是某个时刻的快照，并不是为调用方预留的位置：其他工作进程可能先把它用掉。各进程各自维护同样大小的本地计数器，会放大实际额度，除非存在明确的分配规则，将总预算拆给不同参与者。

把准入决定做成原子操作

把数据放进同一个 Redis 键，不会让客户端的一串命令自动变成原子操作。两个调用方可能都读到尚有额度，各自决定继续，再分别递增。每个 INCR 都是原子的，但之前的比较发生在它外面，所以最后总量仍可能超过承诺，不能只检查单条命令的原子性。

下面的示例将比较、首次创建计数器并附加过期时间、后续递增放进一个很短的 Lua 执行。窗口从首次获准请求开始；拒绝既不增加计数，也不延长截止时间。所有调用方传入同一个键和固定的正参数，实验独占这个数值计数器，不与其他业务共享它的写入权限。

这是从首次到达开始计时的窗口，不是持续滑动的配额。脚本执行不被其他命令交错，也不等于自动回滚、持久预留，或与应用业务操作构成同一个事务。Redis 执行脚本时会阻塞其他服务活动，因此应保持脚本简短；连接丢失应视为结果未知，不能直接断言额度从未被扣除。

准确解释拒绝结果

RFC 6585 用 HTTP 429 表示请求速率过高，但把身份选择和计数政策留给服务器决定。响应应解释条件，可以附带 Retry-After；429 响应不得被缓存保存。整个服务暂时不可用，与某个调用方超过自身额度，是两种不同情况，不应仅为了统一返回格式就抹掉区别。

Retry-After 可以表达建议等待时间，却不保证届时一定有额度。如果公开剩余量或重置时间等元数据，接口契约必须定义单位和范围。历史上不同 API 使用的 X-RateLimit 字段，并不由 RFC 6585 赋予一套通用解释；不能因为名字相似，就把某个平台的字段规则当成统一标准。

坏掉的样子

拆开的检查与更新会在竞争中超额放行。把创建计数器和设置过期时间分成两个命令，还可能因为客户端在中间停止，留下不会过期的计数器。键淘汰、重启或异步故障转移也可能丢失预算状态；一台正常服务器上的原子执行，不能证明这些故障中仍有严格硬上限。

应明确预算存储不可用时，请求是否还能获准。静默把错误当成空计数器，就会凭空创造额度。也要保护限流器本身的容量与响应时间，一起观察允许和拒绝的工作量，并区分必要的资源保护，与没有契约依据地提前拒绝仍有权使用预算的请求。

快速验证

准备 POSIX 环境、C 编译器、make、curl、tar 和 Python 3.10 以上版本。本实验已在 macOS、Redis 8.10.1、redis-py 8.1.0、Python 3.14.4 上运行。安装步骤只构建 Redis 核心，并把客户端装入临时环境，不修改系统级安装。

redis_lab=$(mktemp -d)
curl --fail --location --output "$redis_lab/redis.tar.gz" https://download.redis.io/releases/redis-8.10.1.tar.gz
tar -xzf "$redis_lab/redis.tar.gz" -C "$redis_lab"
make -C "$redis_lab/redis-8.10.1" build redis -j2 MALLOC=libc
export REDIS_SERVER="$redis_lab/redis-8.10.1/src/redis-server"
python3 -m venv "$redis_lab/venv"
"$redis_lab/venv/bin/python" -m pip install redis==8.1.0

在同一个 shell 中，用 "$redis_lab/venv/bin/python" 执行代码。它只启动自己创建的 Redis 进程，通过私有 Unix socket 核对进程身份，关闭 TCP 和持久化，结束后完成清理。十六条独立客户端连接竞争五次准入机会；第一条路径故意展示有错误的检查后更新方式，不应用于真实限流。

from concurrent.futures import ThreadPoolExecutor
from contextlib import contextmanager
import os
from pathlib import Path
import subprocess
from tempfile import TemporaryDirectory
from threading import Barrier
import time

import redis
from redis.backoff import NoBackoff
from redis.retry import Retry


def connection(endpoint):
 return redis.Redis(unix_socket_path=endpoint, decode_responses=False,
 socket_timeout=2, retry=Retry(NoBackoff(), 0))


@contextmanager
def instance():
 with TemporaryDirectory(prefix="redis-budget-", dir="/tmp") as directory:
 endpoint = str(Path(directory) / "redis.sock")
 process = subprocess.Popen([
 os.environ["REDIS_SERVER"], "--port", "0", "--unixsocket", endpoint,
 "--unixsocketperm", "700", "--dir", directory,
 "--save", "", "--appendonly", "no",
 ], stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
 client = connection(endpoint)
 try:
 deadline = time.monotonic() + 5
 while True:
 assert process.poll() is None, "Redis exited during startup"
 try:
 if client.ping():
 break
 except redis.ConnectionError:
 assert time.monotonic() < deadline, "Redis did not start"
 time.sleep(0.02)
 assert client.info("server")["process_id"] == process.pid
 yield client, endpoint
 finally:
 client.close()
 if process.poll() is None:
 process.terminate()
 try:
 _, errors = process.communicate(timeout=5)
 except subprocess.TimeoutExpired:
 process.kill()
 process.communicate()
 raise
 assert process.returncode == 0, errors.decode()


acquire = """
local current = tonumber(redis.call('GET', KEYS[1]) or '0')
if current >= tonumber(ARGV[1]) then
 return {0, current, redis.call('PTTL', KEYS[1])}
end
if current == 0 then
 redis.call('SET', KEYS[1], '1', 'PX', ARGV[2])
else
 redis.call('INCR', KEYS[1])
end
return {1, current + 1, redis.call('PTTL', KEYS[1])}
"""

LIMIT, WINDOW_MS, WORKERS = 5, 60000, 16

with instance() as (control, endpoint):
 def concurrent(operation):
 barrier = Barrier(WORKERS)

 def run(_):
 with connection(endpoint) as client:
 return operation(client, barrier)

 with ThreadPoolExecutor(max_workers=WORKERS) as pool:
 return list(pool.map(run, range(WORKERS)))

 control.set("budget:unsafe", 0)

 def split_check(client, barrier):
 observed = int(client.get("budget:unsafe"))
 barrier.wait(timeout=5) # All callers read before any caller increments.
 if observed >= LIMIT:
 return False
 client.incr("budget:unsafe")
 return True

 unsafe = concurrent(split_check)
 assert sum(unsafe) == WORKERS
 assert int(control.get("budget:unsafe")) == WORKERS
 print("split GET/INCR admits 16 against a budget of 5")

 def atomic_check(client, barrier):
 barrier.wait(timeout=5)
 return client.eval(acquire, 1, "budget:shared", LIMIT, WINDOW_MS)

 results = concurrent(atomic_check)
 assert sum(reply[0] for reply in results) == LIMIT
 assert sorted(reply[1] for reply in results if reply[0]) == list(range(1, LIMIT + 1))
 assert all(reply[1] == LIMIT for reply in results if not reply[0])
 assert all(0 < reply[2] <= WINDOW_MS for reply in results)
 assert control.get("budget:shared") == b"5"
 print("one atomic script admits 5 and rejects 11 across independent client connections")

 ttl_before = control.pttl("budget:shared")
 assert control.eval(acquire, 1, "budget:shared", LIMIT, WINDOW_MS)[:2] == [0, LIMIT]
 assert 0 < control.pttl("budget:shared") <= ttl_before
 assert control.get("budget:shared") == b"5"
 print("a rejection neither spends more budget nor refreshes the window")

 assert control.pexpire("budget:shared", 50)
 deadline = time.monotonic() + 3
 while control.exists("budget:shared"):
 assert time.monotonic() < deadline, "test deadline did not expire"
 time.sleep(0.01)
 first = control.eval(acquire, 1, "budget:shared", LIMIT, WINDOW_MS)
 assert first[:2] == [1, 1] and 0 < first[2] <= WINDOW_MS
 print("after deliberately shortening and expiring the test window, the next admission starts at 1")

同步屏障保证所有不安全调用者都在任何递增发生之前完成读取，因此可以稳定复现十六次获准。原子脚本则恰好放行五次、拒绝十一次，最终计数为五；五个成功回复中的计数从一到五各出现一次。额外拒绝既没有继续花掉预算，也没有刷新原来的过期截止时间。

实验随后主动把自己的截止时间缩短为五十毫秒，等待真实过期，再确认下一次准入从一开始，并获得新窗口。这避免等待整整一分钟，但没有声称测量了一分钟的真实工作负载。集群、故障转移、持久化、HTTP 中间件、生产延迟，以及准入与业务副作用的联动都未在本例中测试。

来源

RFC 6585，第四节的 429 语义、可选 Retry-After 与禁止缓存要求，已核验 2026-09-08。
RFC 9110，Retry-After 与服务不可用语义，已核验 2026-09-08。
Redis 脚本介绍，原子执行和阻塞行为，已核验 2026-09-08。
Redis EVAL，显式传入键与参数，已核验 2026-09-08。
Redis INCR，计数器操作和限流竞争条件，已核验 2026-09-08。
Redis PEXPIRE，隔离实验所用的毫秒过期时间，已核验 2026-09-08。
Redis 8.10.1 构建说明，核心构建与分配器选择，已核验 2026-09-08。

限流 · XB 现场笔记

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

坏掉的样子

快速验证

让等待策略匹配端点需求

来源

令牌桶限制准入并允许突发

先补充额度，再扣除工作成本

突发额度不是峰值速率

预算单位和作用范围要一致

坏掉的样子

快速验证

延伸阅读

来源

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

坏掉的样子

快速验证

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

来源

Retry-After 告诉你何时再试

结合响应语境解释字段值

尊重等待时间，但不无限等待

相同等待值仍可能让调用者同时回来

坏掉的样子

快速验证

延伸阅读

来源

限流需要一个稳定的客户端标识

使用政策真正承诺的身份

地址表示的是网络路径

转发身份必须有信任边界

坏掉的样子

快速验证

延伸阅读

来源

限流是共享预算

先定义政策，再开始计数

把准入决定做成原子操作

准确解释拒绝结果

坏掉的样子

快速验证

延伸阅读

来源