客户端限流实战:令牌桶、漏桶与按主机限流——专家指南
引言:客户端为什么需要自己的限流
想象一下,你走进一家银行,只有一个窗口在营业,而你身后排着一千个人的长队。你可以往前挤,也可以大声喊,但窗口的处理能力并不会因此提高。你要么按合理的节奏来,要么被拒绝。服务端的 rate limit(请求频率限制)就是那位柜员——他终有一天会干脆停止为你服务。而客户端限流,则是你自己决定不去窗口排得比它实际能接待的频率更频繁。
本文完全聚焦于算法。我们有意不重复如何处理 429 状态码、如何做指数退避,也不讨论开多少个线程。这里的重点不同:如何在发出请求之前就先算出现在能不能发,如果不能,还要等多久。正是这套数学,区分了两种客户端:一种"偶尔被拒绝",另一种能常年与同一个 API 合作,而不会惹恼它的所有者。
你将了解到:
- 四类算法——固定窗口、滑动窗口、令牌桶和漏桶——各自如何运作,以及它们在行为层面(而非仅仅名称上)有何不同;
- 为什么令牌桶和 GCRA(漏桶的一种变体)已成为事实标准,以及如何在一个晚上正确实现它们而不出现舍入误差;
- 如何构建分层限流:全局预算、按主机、按端点、按鉴权密钥以及按出口 IP 地址;
- 如何把 IP 轮换融入限流器模型,既不破坏服务端配额,也不破坏自己的遥测;
- 哪些设计错误看起来无害,却会导致无限等待、"整分钟开头的爆发"以及内存泄漏。
我们会用导师式工程师的语言来讲述:有公式,但不晦涩;有示例,但无水词。如果你在写爬虫、为别人的 API 编写 SDK、做电商平台集成,或是构建需要访问数百个主机的聚合器,这份指南值得你加进书签。
基础:什么是客户端限流,为什么光靠服务端不够
看待同一个问题的两种视角
服务端限流保护 API 所有者的基础设施:它统计你的请求,在配额耗尽时回以拒绝。客户端限流解决的是另一个问题——不要让它走到被拒绝那一步。这个区别很关键。服务端是事后反应:请求已经发出、信道被占用、日志被污染、客户端信誉已经略微受损。而客户端是提前行动:它知道(或估算出)预算,并精打细算地花。
为什么不能干脆依赖服务端拒绝然后重试?因为每一次被拒的尝试,都耗费了一次连接、一个鉴权令牌、对方安全日志里的一行记录,而且通常还会让你在自适应防护系统中的位置更差。一个自己遵守节奏的客户端,在服务端眼里是个有教养的合作伙伴。而一个"一直试到被放行"的客户端,看起来就是个麻烦制造者。猜猜下一次调整策略时,谁会被限制得更狠?
基本术语
- Rate(速率)——稳定状态下的请求频率,例如"每秒十个请求"。这是服务端愿意无限期承受的。
- Burst(突发)——不用等待补充就能连续发出的请求数。只要平均速率不被突破,服务端往往容忍短的突发。
- 窗口(window)——统计请求所用的时间区间:一秒、一分钟、一小时、一天。
- 配额(quota)——窗口内允许的最大请求数。配额除以窗口长度就是平均速率。
- 限流键(limit key)——服务端用来归组请求的特征:IP 地址、令牌、账号、"主机加端点"组合。同一个客户端几乎总是同时落入多个键的管辖范围。
- 成本(cost)——请求的权重。有些 API 把搜索算作十个单位,而读取一张卡片算一个。
核心原则:限流器决定"何时",而不是"多少"
一个常见的误解是把限流器和信号量混为一谈。信号量限制并发操作数,回答的是"此刻有多少在途"。限流器限制频率,回答的是"现在能不能再启动一个操作,如果不能,要等多少毫秒"。这两个机制相辅相成,但不能互换。你可能只开一个连接,如果请求很短,照样超限;也可能开一百个连接,如果请求很慢,照样不超限。
好的客户端限流器的三个特性
- 可预测性。 相同输入给出相同结果。绝不会有"偶尔多放行一点"。
- 低成本。 决策以常数时间完成,每个键占用常数内存。如果你有成千上万个主机,限流器不能保存所有请求的历史。
- 公平性。 如果有多个任务在等待许可,它们按顺序获得,而不是按"谁运气好先醒来"。
请把这三个标准记在心里:下一节我们会用它们来比较各种算法。
深入剖析:算法家族及其数学
固定窗口——诚实却狡猾的计数器
最简单的做法:把时间划分为固定长度的窗口,每个窗口维护一个计数器,达到配额就等下一个窗口开始。内存占用——每个键一个数字加一个时间戳。看起来简直是理想方案。
问题叫做窗口边界效应。如果配额是每分钟一百个请求,客户端可以在一个窗口的最后一秒发一百个请求,又在下一个窗口的第一秒发一百个。从客户端角度看,一切都合法:每个窗口恰好一百个。从服务端角度看,两秒内来了两百个请求——比任何合理理解的限制都高出一倍。如果服务端是按滑动窗口计数的(多数现代服务端如此),你会被拒绝,而你却真心觉得自己无辜。
第二个麻烦是突发同步。你的所有工作线程在整分钟开始时同时"醒来",因为计数器恰好在那一刻归零。这会在网络、代理和目标服务器上造成负载尖峰。
滑动窗口日志——精确但昂贵
保存最近一个区间内所有请求的时间戳。发送前丢弃过期的,统计剩余的。计数绝对精确,没有边界效应。但内存随配额线性增长:配额若是一小时一万个请求,你就得为每个键保存一万个时间戳。对一个主机还能忍受,对一千个主机就受不了了。
滑动窗口计数器——折中方案
保存两个计数器:当前窗口的和上一个窗口的。负载估算 = 当前计数器 + 上一个计数器 × 仍在滑动区间内的上一个窗口所占比例。如果当前分钟已过去 20%,就取上一个计数器的 80%。这是个近似值,但能很好地平滑边界,且只需两个变量。许多服务端实现用的正是它,所以客户端模仿它——是"像服务端一样思考"的好办法。
令牌桶——装令牌的桶
想象一个容量为 B 个令牌的桶。每秒往里面滴入 r 个令牌,多出的溢出桶外。要发送成本为 c 的请求,就得取出 c 个令牌。如果没有——就等它滴够。
两个参数给出两个独立的特性。参数 r 是稳定速率:无论你等多久,长期节奏都不会超过每秒 r 个请求。参数 B 是最大突发:空闲之后可以立刻发出 B 个请求。这恰好对应真实服务端策略的表述方式:"每分钟不超过一百个,一次不超过十个"。
实现的关键细节是惰性补充。不需要后台线程每秒去加令牌。每次访问时算出距上次访问过了多少时间,然后补充相应数量即可:tokens = min(B, tokens + elapsed * r)。每个键两个数字,常数时间计算。完全符合低成本标准。
漏桶——带孔的桶
这里的比喻反过来了:请求倒进桶里,从桶底的孔以恒定速率 r 流出。桶溢出了——新请求被拒绝或等待。输出始终均匀:没有任何突发,严格每 1/r 秒一个请求。如果服务端不容忍突发,或者你想让流量曲线尽可能平滑,那就选它。
漏桶有两种理解方式。第一种——当作队列:请求真的被放进缓冲区,由独立进程按计时器放出。第二种——当作计数器:我们只是检查想象中的桶是否会溢出,要么放行,要么不放。第二种理解在电信领域被称为 GCRA(Generic Cell Rate Algorithm),数学上等价于另一种参数化的令牌桶。这是个重要观察:如果你已经实现了令牌桶,你也就已经会做漏桶了。
GCRA:一个时间戳代替计数器
GCRA 只保存一个值——TAT(theoretical arrival time,理论到达时间):下一个"理想"请求不应早于的时刻。参数:发射间隔 T = 1/r,容差 τ 等于 (B − 1) * T。算法如下:
- 获取当前时间 now。
- 如果 TAT 小于 now,就把 TAT 设为 now(桶早已空置)。
- 如果 TAT − τ 大于 now——请求来得太早;等待时间 = TAT − τ − now。
- 否则放行请求,并把 TAT 向前推进 T。
每个键一个数字,无需会逐渐漂移的浮点计数器。正因如此,GCRA 是分布式限流器的首选算法:它的状态可以轻松存放在一个键值字段中并原子更新。
比较表(用文字描述)
- 固定窗口:内存占用最小,精度低,边界有突发,只适合作为粗略保险。
- 滑动日志:绝对精确,内存随配额线性增长,适合键少、配额小的情况。
- 滑动计数器:内存两个变量,精度近似,能很好地模仿服务端逻辑。
- 令牌桶:内存两个变量,可明确控制突发,客户端 SDK 的标准。
- 漏桶 / GCRA:内存一个变量,输出理想均匀,分布式系统的标准。
关于时钟:单调性与漂移
所有算法都依赖"当前时间"。请使用单调时钟(monotonic clock),而非系统时间。系统时间在同步时可能倒退,于是你的限流器会以为过了负数秒、把补充清零,或者反过来,给出巨大的突发。单调时钟保证不倒退。唯一的例外是共享存储中的分布式限流器:那里时间取自存储端,而非各个客户端,以免受机器间时钟偏差影响。
方法一:令牌桶实战——无坑实现
第 1 步。选择参数
把服务端策略转换成一对参数 (r, B)。如果文档说"每分钟一百个请求",基础速率 r = 100/60 个令牌每秒。容量 B 是单独的决定。对不熟悉的 API,安全选择是 B 等于窗口配额的 5% 到 10%,即配额一百时取五到十个令牌。这能快速处理一小批,但不会产生那种会被滑动窗口服务端视为违规的尖峰。
更好的做法是留余量:只使用声明的速率的 80%–90%。双方的服务端计数器、网络延迟和舍入误差不可避免地带来偏差,余量能吸收它。
第 2 步。状态结构
对每个键保存:tokens(浮点数,当前令牌数)、last(上次换算的单调时间戳)、rate、capacity。用互斥锁保护状态,或者在异步代码中,用单一的任务仲裁者让所有令牌请求都经过它。
第 3 步。acquire(cost) 算法
- 获取锁。
- now = monotonic(); elapsed = now − last; last = now。
- tokens = min(capacity, tokens + elapsed * rate)。
- 如果 tokens ≥ cost:tokens −= cost;释放锁;返回"零等待"。
- 否则:wait = (cost − tokens) / rate;把令牌扣成负数:tokens −= cost;释放锁;返回 wait。
- 调用方睡眠 wait 秒后发出请求。
注意第五点。扣成负数——这就是预留。它保证了公平:下一次调用会看到负的剩余量,从而得到更大的等待时间,也就是排在前一个后面。没有预留就会出现经典错误:十个任务同时看到零令牌,都算出相同的等待时间,然后同时醒来,制造出本应被限流器阻止的突发。
第 4 步。限制预留深度
负数预留可能无限延伸:如果任务到达速度快于令牌补充速度,等待队列就会增长,最后一个的等待时间会趋向数小时。引入最大延迟(max_delay)。如果算出的 wait 超过阈值,就不要预留,而是返回"限流器过载"错误。让调度器去决定怎么办:推迟、降优先级、切换到别的主机。这正是客户端限流器从被动刹车变成负载管理工具的那个点。
第 5 步。加权成本
允许请求有不同的 cost。搜索端点、批量查询、写操作对服务端来说通常"更贵",许多 API 也在策略中体现了这一点。如果文档没提,就根据自己对响应时间的观察来定权重:服务端处理时间更长的请求,合理算作更贵。等待公式不变——cost 只是作为一个因子进入它。
第 6 步。预热与冷启动
初始 tokens 值是单独的决定。启动时满桶意味着进程一启动就立刻爆发 B 个请求。如果部署后有几十个进程同时启动,这可能就不合适了。更安全的做法是从零或半容量开始。如果已知服务端按与你的启动时刻无关的窗口计配额,零起始反而更诚实。
令牌桶检查清单
- 使用单调时钟。
- 惰性补充,按时间差计算,没有后台计时器。
- 负数预留以实现公平排队。
- 有 max_delay,溢出时明确拒绝。
- 速率相对服务端留有餘量。
- 容量限制在窗口配额的合理比例内。
- 支持 cost 以处理加权请求。
- 初始状态不在部署时制造突发。
方法二:漏桶与 GCRA——需要均匀流量时
何时优先选漏桶
令牌桶允许突发。这很方便,但也有些情况,突发本身就有害:服务端对短时尖峰反应激烈、代理信道带宽有限、你希望流量模式看起来像普通的不紧不慢的客户端。所有这些情况都需要请求之间严格恒定的间隔。这就是漏桶。
作为队列的实现
经典方式:固定容量缓冲区和单一消费者,每 T 秒取出一个元素并发送。优点——简单直观。缺点——需要单独的线程或任务,消费者一停缓冲区就"冻结"。这种方式适合你本来就有明确流水线——任务队列,请求本就从中逐个取出——的场景。
作为 GCRA 的实现
多数客户端场景下,计数器式的理解更方便。上面我们已描述了算法;现在说如何设参数。如果需要严格间隔,就把 τ 设为 0:此时容差为零,请求不会比每 T 秒一次更频繁。如果想允许小的突发,就增大 τ。这样一套实现既覆盖严格漏桶,也覆盖令牌桶。正因如此,GCRA 是限流库不错的"统一引擎"。
带预留的 GCRA 分步流程
- 读取该键的 TAT;如果没有,就把 TAT 设为 now。
- new_TAT = max(TAT, now) + T * cost。
- allow_at = new_TAT − τ − T * cost;这是这种成本的请求本可无需等待发出的时刻。
- 如果 allow_at ≤ now:写入 new_TAT,返回"零等待"。
- 否则:wait = allow_at − now;如果 wait 大于 max_delay——不写入直接拒绝;否则写入 new_TAT 并返回 wait。
在分布式存储中,第 1 到第 5 步用一次原子操作完成——例如存储端的脚本。这保证两个客户端不会读到同一个 TAT 并"重复"获得许可。
等价性与按负载性质选择
理解这一点很有用:参数为 (r, B) 的令牌桶和参数为 (T = 1/r, τ = (B − 1)/r) 的 GCRA 放行完全相同的请求序列。区别只在状态表示。所以"哪个更好"其实该这么问:你需不需要突发。需要——就让 B 大于一。不需要——就让 B = 1(τ = 0)。其余都是口味和存储便利的问题。
漏桶 / GCRA 检查清单
- 已决定是否需要突发,还是严格均匀流量。
- 状态是每个键一个 TAT 值。
- 读-检查-写操作是原子的。
- 有 max_delay,溢出时明确拒绝。
- 分布式版本中时间取自存储端。
方法三:按主机限流——注册表、分层与组合
为什么"一个限流器管所有"行不通
如果你的客户端只访问一个 API,一个桶就够了。但聚合器、爬虫和集成总线要访问几十上百个主机,每个都有自己的策略。单一的全局限制要么浪费了快主机,要么压垮了慢主机。你需要一个限流器注册表:"限流键——桶状态"的映射,键由请求的特征构成。
限流键:从主机到端点
最小的键是方案加主机加端口。同一所有者的两个域名常共享配额,而子域名可能单独计算;这需要从文档中了解或通过观察判断。更细的键是主机加路径模板:例如搜索端点和商品卡片端点各有不同配额。再细一点是主机加鉴权令牌,如果服务端按 API 密钥计配额,而你有多个密钥。
实用规则:键要由与服务端计数相同的特征构成。如果服务端按 IP 计,键里就包含你的出口 IP。如果按令牌——就包含令牌。如果两者同时——你就需要两个限流器,请求必须同时通过两者。
限流的分层
设计良好的系统会按层级布置限流器:
- 全局——进程的总预算。保护你自己的资源:套接字、内存、信道带宽。
- 按出口 IP——通过特定地址发出多少请求。在使用地址池时,这是关键层级。
- 按主机——目标服务器的整体策略。
- 按端点——昂贵方法有单独配额。
- 按凭证——令牌或账号的配额。
请求必须在每一层都获得许可。这就是限流器的组合。
无死锁的组合
天真的做法是依次对每个限流器调用 acquire 并累加等待时间。这是错的:第一个限流器已经扣了令牌,而第二个让你等十秒,这十秒里第一个的令牌从公平角度看已经"过期"了。更糟的是,两个任务以不同顺序获取限流器,可能无限互相干扰。
正确的流程:
- 对每个限流器计算等待时间,但不扣减(peek 操作)。
- 取等待时间的最大值——这是总 wait。
- 如果 wait 超过 max_delay——拒绝。
- 否则在所有限流器中扣减,传入统一的到达时间 now + wait,让每个都为同一时刻预留资源。
- 睡眠 wait 后发送。
始终按同一固定顺序遍历限流器(例如从全局到最窄)。这样并发访问时就不会死锁。
配置与默认值
注册表必须能为从未见过的主机创建限流器。设定保守默认值:低速率、极小突发。已知主机——用显式配置。好做法是把策略以声明式保存:主机或模板、rate、burst、按路径模板的 cost、"按 IP 计"和"按令牌计"标志。这样服务端策略变化时只改一个文件,而非代码。
淘汰与泄漏
有上千主机的注册表是内存泄漏的潜在来源。很久没访问的主机需要淘汰。由于桶状态在长时间空闲后反正会"满"(或 TAT 落在过去),淘汰不会丢失信息:下次访问时限流器会以相同状态重新创建。使用有大小限制的 LRU 缓存,或定期清理 last 早于几个窗口的记录。
按主机限流检查清单
- 限流键重复服务端计数的特征。
- 有层级:全局、IP、主机、端点、凭证。
- 组合通过 peek—取最大值—统一扣减。
- 限流器按固定顺序遍历。
- 对未知主机有保守默认值。
- 策略提取到配置中。
- 注册表有大小限制并淘汰不活跃键。
方法四:限流器与 IP 轮换——如何在模型中考虑地址切换
为什么轮换会破坏天真的限流器
如果目标服务器按 IP 计配额,那么切换地址就改变了服务端的限流键。天真的客户端若只维护一个按主机计的计数器,切 IP 后会继续憋着,尽管服务端已看到"新访客"。反向的错误更危险:客户端在切 IP 时重置所有限流,包括服务端按令牌或账号计的限流——于是被一个与 IP 毫无关系的配额拒绝。结论:轮换只应影响分层中的"按出口 IP"层级,其他层级各行其道。
地址切换的两种模式
在 Proxeon 基础设施中,端口上的 IP 要么按计时器切换,要么通过链接/API 切换(截至 2026 年 9 月 22 日的数据)。这是限流器的两种本质不同的场景。计时切换时客户端无法控制时刻:地址"由外部"变化,IP 限流器必须得知——通过事件、轮询当前地址,或在间隔已知时按时间表。通过链接切换时客户端自行发起,并可将切换与自己的状态同步:等待在途请求完成,固定时刻,建立新的"主机加 IP 纪元"键。
每种模式有多普遍?截至 2026 年 11 月 14 日的数据,按计时器切换 IP 占 51.1%,其余为通过链接/API 切换。也就是说两种策略出现频率大致相当,通用限流器必须同时支持两者。
地址纪元作为键的一部分
与其把 IP 本身放进键(也可能事先不知道),不如使用纪元——每次切换时递增的计数器。"按 IP"层级的键变成"端口加纪元"对。切换纪元时,旧键不再使用,随后被注册表淘汰,新键以初始状态创建。注意:初始状态同样应当保守。新地址对服务端来说是陌生人,它看到的第一件事——就是你的流量模式。
限流窗口与轮换计时器的协调
截至 2026 年 11 月 14 日的数据,计时器切换 IP 的间隔中位数是 120 秒,78.1% 的计时器间隔恰好是整分钟倍数。这对设计非常方便。如果你的按主机的"按 IP 每分钟 N 个请求"配额在,而地址存活两分钟,那么一个地址的预算恰好是两个窗口。IP 限流器可以按速率 N/60 的令牌桶工作,容量计算得使地址生命周期内不超过 2N。重要的是不要"追赶"漏掉的:如果第一分钟发得少,第二分钟不能发双倍,因为服务端按分钟窗口计,而不是按你的纪元计。
切换期间的暂停
地址切换并非瞬间完成。截至 2026 年 11 月 14 日的数据,切换本身(从命令到新地址)的平均时长是 4.56 秒,80.8% 的切换在 5 秒内完成。这对限流器意味着什么?切换期间请求要么通过旧地址发出,要么根本发不出。正确策略是把切换视为短暂的"排空"区间:切换命令前,限流器停止发放新许可,等待在途请求完成,执行切换,然后开启新纪元。既然五次切换中有四次在五秒内完成,把等待新地址的超时设得略高于这个值,超时就转入异常处理,是合理的。
限制切换命令本身的频率
这是个常被忽略的洞见:切换 IP 的命令也是对 API 的请求,它同样需要限流。截至 2026 年 11 月 14 日的数据,通过链接的重复切换记录(间隔不超过 2 秒、同一 IP)占 1.2%。这是客户端连续两次触发链接的情形留下的痕迹:源于工作线程间的竞态、超时后的重试,或缺少单一决策点。解决办法是在切换命令上配一个容量为一、间隔严格的桶(τ = 0 的纯漏桶),加上去重:如果切换已在进行,其他工作线程就等它的结果,而不是再发起一次。这个原则和针对目标主机的一样,只是用在了你自己的基础设施上。
规模与预算规划
感受一下规模:截至 2026 年 11 月 14 日的数据,Proxeon 全网单日完成 2 196 242 次 IP 切换,涉及 7 924 个代理端口,单个调制解调器单日唯一 IP 数的中位数是 95。对限流器设计者来说,这意味着一个端口一天会经过几十个地址纪元,"按 IP"状态必须轻量且易于快速淘汰:保存所有纪元的历史毫无意义,但保证新纪元创建成本恒等——是必须的。
协议与端口寻址
一个简化配置的小细节:在 Proxeon 中,SOCKS5 端口等于 HTTP 端口加一(截至 2026 年 9 月 22 日的数据)。如果你为同一信道使用两种协议,IP 限流器应把它们视为一个键而非两个:它们的地址是共享的,所以预算也共享。在注册表中记下归一化规则:键按 HTTP 端口构建,SOCKS5 端口减一归一。
分布式 IP 限流器
当一个端口由多个进程或机器共用时,桶必须共享。使用支持原子操作的存储,把 TAT(GCRA)存在"端口加纪元加主机"的键下,用存储端脚本更新,时间也从那里取。纪元同样集中保存,并与切换命令一起原子更新,这样所有进程协同切换到新键。
轮换时的限流器检查清单
- 轮换只影响"按 IP"层级,其他层级不重置。
- 两种模式都支持:计时器和通过链接/API 切换。
- IP 层级键包含地址纪元。
- 新纪元以保守状态启动。
- 按 IP 的速率与服务端窗口对齐,而非与纪元长度对齐。
- 切换期间暂停发放许可。
- 切换命令本身被限流并去重。
- 同一信道的 HTTP 和 SOCKS5 端口归一化为一个键。
- 多进程场景下状态存入共享存储。
客户端限流的典型设计错误
错误 1. 用 sleep 代替限流器
"在请求间放一百毫秒暂停"——最常见的方案,也是最脆弱的。它不考虑请求本身耗时,在多工作线程下失效,在允许突发的地方不给突发,在禁止突发的地方也防不住。暂停不是限流器,而是它的模仿。
错误 2. 服务端按滑动计,你却按窗口计
窗口边界效应已在上文剖析。如果你不确定服务端怎么计,就假定最坏情况——滑动窗口——并使用容量克制的令牌桶。
错误 3. 没有预留的竞态
多个任务同时算出相同等待时间、睡着、一起醒来。结果正是限流器本应阻止的那个突发。用锁下的预留(扣成负数或推进 TAT)来治。
错误 4. 无限等待队列
没有 max_delay,队列无限增长,任务等上几分钟甚至几小时,占用内存和连接。限流器必须能拒绝。
错误 5. 系统时钟
同步时一次跳变——桶要么溢出,要么"冻结"。客户端只用单调时钟;分布式版本只用存储端时间。
错误 6. 切 IP 时重置所有限流
按令牌和账号的配额与地址无关。你一旦重置它们,就立刻违反了与你无关的策略。
错误 7. 启动时满桶
部署后几十个进程以满桶启动,同时爆发。从空桶开始,或加入随机启动延迟。
错误 8. 无淘汰的注册表
每个新主机——一条永久记录。运行几周后,进程内存里全是再也不会用到的主机限流器。
错误 9. 忽略请求成本
如果服务端把搜索算作十个单位,而你算作一个,你的限流器会放行十倍于应有的量,然后被拒绝时真心惊讶。
错误 10. 无限切换命令
因超时或多个工作线程重复发出切换地址的命令,导致重复和多余的切换。命令也是资源;给它一个桶。
实现工具与资源
各生态的现成库
- Go:包 golang.org/x/time/rate——令牌桶的参考实现,含 Allow、Reserve、Wait 方法。Reserve 返回带等待时间和取消能力的对象——正是组合所需。
- Python:库 limits 提供带多种后端的固定窗口、滑动窗口和 GCRA;aiolimiter 为 asyncio 实现漏桶;pyrate-limiter 支持同时多个窗口。
- Java/Kotlin:Bucket4j——成熟的令牌桶,支持分布式存储;Resilience4j RateLimiter——带固定刷新周期的变体。
- JavaScript/TypeScript:bottleneck 能按键组限流并通过共享存储集群化;p-throttle——简单场景的极简方案。
- Rust:governor——GCRA 实现,带键和不带键,适用于异步代码。
- .NET:内建的 System.Threading.RateLimiting 命名空间,含令牌桶、滑动窗口和按键分区限流器。
分布式状态的存储
Redis 及支持服务端脚本的兼容存储——共享 GCRA 的标准做法:一次原子操作,时间取存储端命令,键带 TTL 自动淘汰。对单应用集群内的场景,带原子操作的分布式缓存之类的内建机制也适用。
可观测性工具
没有指标的限流器是黑盒。导出:无等待放行数、等待时间分布、因 max_delay 拒绝数、各键桶的当前填充度、地址纪元切换频率。按主机的等待时间直方图会立刻告诉你哪里策略太紧,哪里你已濒临极限。
地址基础设施
有轮换场景就需要一个提供两种地址切换模式——计时器和链接/API——以及可预测端口寻址的提供商。在 Proxeon,两种模式都可用,且 SOCKS5 端口恰好比 HTTP 端口大一(截至 2026 年 9 月 22 日的数据),这简化了限流器注册表中的键归一化。
延伸阅读
- 电信标准规范中的 GCRA 描述——漏桶作为计数器的原始出处。
- x/time/rate 包的文档——Reserve 和 Wait 语义的样板式表述。
- 大型公共 API 文档中关于限额的章节——那里有各种计数模型,是学习把策略转换成桶参数的最佳途径。
案例与应用场景
场景 1. 覆盖数百主机的价格聚合器
任务:定期遍历众多平台上的商品卡片,每个平台有自己的策略。方案:限流器注册表,键为"主机加路径模板",新平台用保守默认值,已知平台用显式策略。与按套接字数的全局限流组合。这类系统追求的结果:所有主机负载均衡,快主机不闲置,慢主机不过载;平台策略变化时只改一行配置。主要教训——从单一全局限流转到分层,能大幅降低"白发送"请求的比例。
场景 2. 合作伙伴 API 的 SDK,配额按令牌和按 IP
任务:为客户提供的库,客户有多个令牌和多个出口地址。方案:两个限流层级——按令牌和按地址——通过 peek 和统一到达时间组合。调度器挑选等待时间最小的"令牌加地址"组合。教训——限流器变成了路由工具:与其"等待",它建议"发往哪里才能不等待"。
场景 3. 计时轮换的移动地址爬虫
任务:通过端口池抓取公开页面,地址按计时器切换。方案:按 IP 限流器,键为"端口加纪元",速率与目标主机的分钟窗口对齐。鉴于截至 2026 年 11 月 14 日的数据,计时器间隔中位数是 120 秒、78.1% 的间隔为整分钟倍数,纪元预算按整数个分钟窗口计算。切换期间——80.8% 的切换在 5 秒内完成(截至 2026 年 11 月 14 日的数据)——暂停发放许可,超时设得略高于此值。教训——让限流窗口与轮换节奏对齐,可避免新纪元开头的"追赶"突发。
场景 4. 通过链接轮换且命令重复的工作线程
任务:多个工作线程共用一个端口,需要时各自发起切换地址。症状——日志中有重复命令的痕迹。方案:单一轮换点,配漏桶(τ = 0)和去重:如果切换已在进行,其他人等它完成。截至 2026 年 11 月 14 日的数据,全网通过链接的重复切换记录占 1.2%;这正是一个单一决策点能消除的情形。教训——不仅要限制对他人 API 的请求,也要限制对自己基础设施的命令。
场景 5. 用 GCRA 统一所有层级的单一引擎
任务:简化一个历史上曾并存固定窗口、sleep 暂停和手写计数器的代码库。方案:一个 GCRA 实现,参数为 (T, τ),应用于所有层级,分布式键的状态存共享存储,本地键的状态存内存。教训——一个公式取代了各种方案的杂烩,使系统行为可预测。
FAQ:疑难问题解答
既然令牌桶和漏桶等价,它们本质上有什么区别?
作为数学对象它们是等价的:正确对应参数后,放行完全相同的请求序列。区别在于直觉和你能直接控制哪个参数。令牌桶以"速率和突发"来思考,漏桶以"间隔和容差"来思考。对于"每分钟 N 个,一次不超过 M 个"这类策略,前者更方便;对于"严格每 T 秒一个请求",后者更方便。GCRA 把两种直觉统一在一个状态里。
如果服务端不公布允许的突发量,如何选择桶容量?
从窗口配额的小比例开始——大约 5% 到 10%——然后观察。如果没有拒绝且等待时间长,再谨慎增大。记住,滑动窗口服务端不容忍超过短子区间配额的突发,所以容量绝不能接近完整配额。
如果只有一个线程,还需要限流器吗?
需要。一个线程用短请求很容易超配额:如果响应二十毫秒就到,你会每秒发五十个请求,甚至都没意识到。限流器与线程数无关;它解决的问题和信号量不同。
如果服务端对成本计算不同,如何对成本不同的请求限流?
把 cost 传给 acquire。令牌按比例扣除,等待时间按同一公式算。如果成本未知,按响应时间或响应大小估算,并随着观察修正。宁可高估,也别低估。
如果一个请求要过五个限流器,而每个给出不同等待时间,怎么办?
先问所有限流器的等待时间而不扣减,取最大值,然后在同一到达时刻对所有限流器扣减。始终按同一顺序遍历。如果最大值超过阈值,不扣减直接拒绝,否则资源会被"白白"预留。
如果不知道确切时刻,限流器应如何响应计时器切 IP?
用事件或轮询当前地址,若已知间隔则用带余量的时间表。在 Proxeon,计时切换和链接/API 切换都是标准模式(截至 2026 年 9 月 22 日的数据),如果你需要精确同步,优先选链接模式:那时切换时刻由你决定,你可在切换确认的那一刻才对注册表开启新纪元。
为什么切地址后不能重置所有限流?
因为服务端可能同时按多个特征计配额。地址变了——按 IP 的配额重新开始,但按令牌、账号或会话的配额仍在计数。全部重置,就会违反那些与地址无关的策略。轮换只应触及分层中的"按 IP"层级。
分布式限流器,令牌桶还是 GCRA 更好?
GCRA。它只有一个状态值,原子更新更容易,带 TTL 存储也更简单。令牌桶需要两个值,补充逻辑稍复杂,也就使原子脚本更难。语义上二者结果相同。
上线前如何验证限流器工作正确?
用可替换的时钟写测试:在给定时刻送入请求,与参考序列比对。检查边界情况:零时间、长时间空闲、许多请求同时到达、成本大于容量(应明确拒绝,而非无限等待)。单独测试组合:两个不同速率的限流器,验证任一个都不放行超过自己的配额。
结论:下一步做什么
客户端限流不是刹车,而是控制系统。正确构建的限流器做三件事:不走到被拒绝、均匀使用可用预算、告诉调度器下一个请求何时发往何处。核心——只有一个公式,无论是令牌桶还是 GCRA——但需要围绕它建立纪律:单调时钟、锁下预留、最大延迟、键的分层与淘汰。
简要总结:
- 固定窗口简单,但边界狡猾;优先选令牌桶或 GCRA。
- 令牌桶分别控制速率和突发;GCRA 用单个状态数做到同样的事。
- 限流键重复服务端计数的特征;限流器分层,通过 peek—取最大值—统一扣减组合。
- 地址轮换只改变"按 IP"层级;切换命令本身也配得上自己的桶。
- 等待时间和拒绝的指标——是了解你的策略与服务端吻合程度的唯一诚实方式。
给你的下一步:选定统一引擎(我们建议 GCRA),在配置里描述已知主机的策略,加一个保守默认值,开启指标,用可替换时钟跑测试。如果你通过地址池工作,就把纪元加入键,并为切换命令加单独的桶。此后,你的客户端对任何服务端来说都像最礼貌的客人——那个永远不被拒绝的人。