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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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 是请求唯一 ID，score 是时间戳 {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": f"ping {i}"}], "max_tokens": 16 } r = requests.post(URL, json=payload, headers=HEADERS, timeout=10) return r.status_code with concurrent.futures.ThreadPoolExecutor(max_workers=50) 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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。需要临时验证模型行为、看限流触发后的返回长什么样，用模型对话页面直接试：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。
最后留一个我踩过的坑：降级到本地内存时，local_max_requests千万别设得和全局配额一样大。本地配额是单节点算的，N 个节点会放大 N 倍。我一开始图省事设成 3000，结果 Redis 一挂，实际放行量直接飙到全局上限的好几倍。后来改成 50，降级期间虽然配额失守，但至少不会瞬间打穿成本。降级是显式选择，不是缺陷，把本地配额设小，就是给这个选择加一道保险。
