1. 多节点部署下单机限流为什么等于没限你如果只在一台机器上跑过限流很容易产生一种错觉max_requests 30写进配置服务就安全了。可一旦把同一个服务扩到 10 个 Pod、20 个容器事情就完全变了。每个节点各自维护一份内存计数器各自放行 30 QPS全局实际放行量就是 30 乘以节点数。节点越多配额被放大得越离谱限流形同虚设。这就是成本限流在多节点场景下的第一个坑限流状态必须跨节点共享。请求次数要共享Token 消耗更要共享因为大模型调用是按 Token 计费的一次长上下文请求可能顶几十次短请求。如果只按请求数限流一个用户用超长 prompt 就能把成本打穿。我这次要落地的场景是一个多实例部署的 Agent 服务前面挂负载均衡后面调大模型。需求有三条。第一全局配额要准不管扩多少节点整体不能超过设定上限。第二要按业务分区比如免费用户、付费用户、内部调试走不同阈值某个分区被打爆时只降级这个分区不牵连其他。第三Redis 万一不可用服务不能整体挂掉要有明确的降级行为。下面这套骨架就是围绕这三点设计的用 Redis ZSET 做跨节点滑动窗口用分区前缀隔离业务用本地内存做 Redis 分区时的降级兜底。配置和代码都可以直接抄改改 key 前缀和阈值就能用。2. TaoToken 前置统一 Key 与 API 通道在讲限流之前先把调用通道理顺。多节点服务如果每个节点各配一套 Key配额统计和成本归因会非常乱。我的做法是让所有节点走同一个统一通道Key 集中管理这样限流器统计的 Token 消耗和实际计费口径才对得上。TaoToken 在这里扮演的是统一 API 通道的角色官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你可以在控制台里创建 Key然后让所有节点共用同一个 Key或者按业务分区创建多个 Key分别对应不同的限流分区。如果你用的是 Claude Code 这类编码工具可以通过 CC Switch 把请求切到统一通道。下面这段settings.json片段就是接入配置把 base URL 指向 TaoToken 的 API 地址Key 填你在控制台生成的那一串{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [Bash, Read, Write] } }这里有个细节要注意ANTHROPIC_BASE_URL只写到/api不要自己拼/v1之类的路径具体路由由通道侧处理。Key 建议放在环境变量或密钥管理里不要硬编码进仓库。如果你需要按分区用不同 Key就在每个分区的配置里替换ANTHROPIC_AUTH_TOKEN限流器的分区名和 Key 的分区名保持一致后面排查问题时能一眼对上。创建 Key 的入口在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里面有各语言的调用示例配限流器时对着看就行。3. 可复制的 config.toml 与 Redis Key 骨架限流器的行为全部由配置驱动这样调阈值不用改代码。下面这份config.toml覆盖了 Redis 连接、全局配额、分区阈值、降级策略四块。我把它拆开讲你照着填自己的值。[redis] addr 127.0.0.1:6379 password db 0 pool_size 32 dial_timeout_ms 200 read_timeout_ms 100 [limiter] # 滑动窗口长度单位秒 window_seconds 60 # 全局请求数上限所有节点共享 global_max_requests 3000 # 全局 Token 上限所有节点共享 global_max_tokens 2000000 # key 前缀多环境隔离用 key_prefix ratelimit:prod [limiter.partitions.free] max_requests 300 max_tokens 100000 # 超过阈值后的降级动作reject / throttle / fallback on_exceed reject [limiter.partitions.paid] max_requests 2000 max_tokens 1500000 on_exceed throttle [limiter.partitions.internal] max_requests 5000 max_tokens 5000000 on_exceed fallback [degrade] # Redis 不可达时是否降级到本地内存 enabled true # 本地内存配额按单节点算故意设小 local_max_requests 50 local_max_tokens 20000 # 降级状态下的日志级别 log_level warn配置里几个关键点解释一下。window_seconds是滑动窗口长度60 秒意味着统计最近一分钟的请求。global_max_requests是所有节点加起来的上限这个值才是真正生效的全局配额。分区阈值是全局配额之下的细分free分区被打爆不影响paid。on_exceed有三种动作reject直接拒绝throttle排队限速fallback放行但打标记适合内部调试。Redis Key 的设计决定了限流能不能按分区隔离。我用的是分层前缀加 ZSET 结构骨架如下# 请求数滑动窗口member 是请求唯一 IDscore 是时间戳 {key_prefix}:req:{partition}:{client_id} # Token 消耗滑动窗口member 是 预占ID:token数score 是时间戳 {key_prefix}:tok:{partition}:{client_id} # 全局请求计数所有分区汇总用于总闸 {key_prefix}:req:__global__ # 全局 Token 计数 {key_prefix}:tok:__global__实际展开后长这样ratelimit:prod:req:free:user_1024 ratelimit:prod:tok:free:user_1024 ratelimit:prod:req:__global__ ratelimit:prod:tok:__global__为什么用 ZSET 而不是简单的 INCR因为滑动窗口需要按时间淘汰旧记录。ZSET 的 score 存时间戳每次请求先ZREMRANGEBYSCORE清掉窗口外的旧成员再ZCARD数当前窗口内的数量最后ZADD写入本次请求。三步在一个 Lua 脚本里原子执行避免多节点并发时的竞态。Token 限流比请求数复杂一层因为真实 Token 数要等调用结束才知道。我用的是预占加修正的两阶段调用前按预估 Token 数写入一条带:estimated后缀的成员调用结束后ZREM掉预占条目再ZADD真实值。这样并发请求不会同时以为还有额度预估是草稿实报是定稿。4. 验证请求与降级触发实测配置写完得验证两件事正常情况下滑动窗口是否按预期计数Redis 挂掉后降级是否真的生效。下面是我实测的步骤。先起一个本地 Redis确认连通redis-cli -h 127.0.0.1 -p 6379 ping # 返回 PONG 即正常然后写一个最小压测脚本模拟多节点并发请求。这里用 Python 的concurrent.futures起 50 个线程每个线程打 100 次请求观察限流器放行数import concurrent.futures import requests URL http://127.0.0.1:8080/v1/chat/completions HEADERS {Authorization: Bearer sk-你的TaoToken密钥} def one_call(i): payload { model: claude-sonnet-4-20250514, messages: [{role: user, content: fping {i}}], max_tokens: 16 } r requests.post(URL, jsonpayload, headersHEADERS, timeout10) return r.status_code with concurrent.futures.ThreadPoolExecutor(max_workers50) as ex: results list(ex.map(one_call, range(5000))) from collections import Counter print(Counter(results))把free分区的max_requests临时调到 300跑完 5000 次请求预期结果是 300 个 200、4700 个 429。实测下来计数误差在个位数以内说明跨节点共享生效了。你可以同时开两个服务实例各自打请求总数依然卡在 300这就是全局配额的意义。验证降级触发直接把 Redis 停掉redis-cli -h 127.0.0.1 -p 6379 shutdown nosave再跑一次压测。此时限流器应该回退到本地内存每个节点按local_max_requests 50放行。你会看到放行数明显上升因为本地配额是单节点算的多节点会放大。日志里会出现degrade to local memory的 warn 记录。这正是 AP 取舍Redis 分区时保可用配额暂时失守靠下游兜底。恢复 Redis 后再跑一次确认限流器自动切回共享模式redis-cli -h 127.0.0.1 -p 6379 ping # PONG配额回收的验证看 ZSET 成员数。窗口是 60 秒等 61 秒后再查redis-cli ZCARD ratelimit:prod:req:free:user_1024 # 预期返回 0旧成员已被 ZREMRANGEBYSCORE 清掉如果返回的不是 0检查 Lua 脚本里的ZREMRANGEBYSCORE是否用了正确的窗口下界常见错误是把now - window写成了now。5. 本篇常见错排查报错一WRONGTYPE Operation against a key holding the wrong kind of value这个报错说明同一个 key 被当成了不同类型操作。比如ratelimit:prod:req:free:user_1024之前被SET成字符串现在又用ZADD操作。排查方法是用TYPE命令看 key 类型redis-cli TYPE ratelimit:prod:req:free:user_1024 # 预期返回 zset如果返回 string说明有旧代码在写这个 key清掉重建即可。根治办法是统一 key 前缀别让不同版本的代码共用同一个前缀。报错二限流计数偏大实际放行数远低于配额多半是预占 Token 没被正确移除。检查report_tokens阶段是否用ZREM删掉了带:estimated后缀的成员。如果预占条目残留ZCARD会把它们算进去导致额度被虚占。排查命令redis-cli ZRANGE ratelimit:prod:tok:free:user_1024 0 -1 WITHSCORES看成员里有没有:estimated结尾的残留。有的话说明调用异常时没走到修正逻辑需要在异常分支里补一个ZREM。报错三Redis 恢复后限流器没切回共享模式降级状态通常有个标志位Redis 恢复后需要重置。检查你的健康检查逻辑是否定期 ping Redis以及降级标志是否有超时回切。如果用的是连接池连接断开后池子里的旧连接可能还在报错需要重建连接池。实测中我遇到过池子没刷新导致一直走本地内存的情况加一个定时探活就解决了。报错四分区阈值不生效所有分区共用全局配额检查 key 里的{partition}是否真的被替换了。如果配置解析时分区名没传进去所有请求会落到同一个 key 上。打印实际生成的 key 确认ratelimit:prod:req:free:user_1024 # 正确 ratelimit:prod:req::user_1024 # 分区名为空错误分区名为空时所有业务共用一份计数免费用户会把付费用户的额度吃掉。6. 把通道和限流串起来限流器统计的 Token 消耗最终要和实际计费口径对齐否则你限的是自己的账不是真实的账。所以统一通道这一步不能省。所有节点走同一个 TaoToken Key限流器读到的 Token 数和通道侧记录的一致成本归因才准。如果你是按分区用不同 Key就在config.toml的每个分区里配对应的 Key限流器的分区名和 Key 名保持一致。这样某个分区被打爆时你能直接定位到是哪个 Key 在超支。长期跑编码任务或 Agent 的话可以考虑 Coding Plan配额和限流策略能统一管理https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。需要临时验证模型行为、看限流触发后的返回长什么样用模型对话页面直接试https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。最后留一个我踩过的坑降级到本地内存时local_max_requests千万别设得和全局配额一样大。本地配额是单节点算的N 个节点会放大 N 倍。我一开始图省事设成 3000结果 Redis 一挂实际放行量直接飙到全局上限的好几倍。后来改成 50降级期间虽然配额失守但至少不会瞬间打穿成本。降级是显式选择不是缺陷把本地配额设小就是给这个选择加一道保险。