LiteLLM网关Redis内存打满引发级联故障的复盘与优化实践

做生产环境的技术人最怕的不是模型 provider 出故障而是自家网关这一层先崩。那天凌晨LiteLLM 网关的 5xx 率在十分钟内从 0.1% 冲到 67%Redis 内存告警紧随其后紧接着业务方反馈大批模型调用失败——一次典型的级联故障就这么炸开了。这篇复盘我从头到尾梳理了 LiteLLM 网关依赖 Redis 做限流与缓存时内存被打满后如何一步步传导成全站故障以及恢复过程中沉淀下来的内存优化措施。如果你正在用 LiteLLM、one-api 这类 LLM 网关或者打算给网关引入一个共享 Redis 状态层这篇内容应该能帮你少踩几个坑。1. 事故时间线从一条预警到全站请求失败1.1 凌晨 1 点的告警顺序那天是周四凌晨值班手机先响的是 Redis 内存告警某个共享 Redis 实例的内存水位到了 86%。我当时看了一眼心想“还能撑一会儿白天再处理”结果五分钟之后第二条告警就上来了——LiteLLM 网关的 5xx 比例超过了 10%并且还在往上跳。第三条是业务方在群里直接开麦“大模型接口大面积超时是不是上游挂了”告警顺序只是表象真正让人紧张的是下面这几个数据Redis 侧used_memory1.78GBmaxmemory2GBmem_fragmentation_ratio1.84keyspace里 db0 的 keys 284 万其中带过期时间的 221 万意味着有 63 万个 key 没有 TTL。LiteLLM 侧请求错误率从 0.1% 涨到 67%峰值 p95 延迟从正常时的 300ms 拉到 8 秒以上。K8s 侧网关 Pod 开始出现重启部分副本的健康检查失败容器被自动杀掉再拉起来。这三组状态单独看都“很严重但能解释”Redis 内存高、网关报错、Pod 重启。但把它们放到同一段时间轴上才发现是一条完整的故障传导链。当时我们并没有第一时间把三张看板的曲线叠在一起看这也是第一轮排查走弯路的主要原因。1.2 第一轮排查为什么走偏了凌晨两点任何人打开 LiteLLM 的日志第一反应大概率和我一样先怀疑模型上游。因为我们看到的大部分报错都带着 timeout、connection reset、5xx 这类字眼非常像 OpenAI、Bedrock 这类模型服务商出了状况。于是我们先后做了三件事检查模型服务商状态页、看是否触发了上游限流、重放几个失败请求。这三件事做完结论却对不上上游状态页一切正常重放请求也是成功的但生产环境仍然在持续报错。更让人困惑的是错误率曲线和 Redis 内存曲线几乎是同步往上走的。直到有人把 Redis 的INFO errorstats拉出来看到里面有大量OOM command not allowed when used memory maxmemory的错误计数我们才反应过来不是模型方的问题是我们自己托管状态的 Redis 先扛不住了。现在回过头看这个弯路其实完全可以避免。网关报错的第一现场确实像“上游故障”但如果当时先把 Redis 的evicted_keys、INFO errorstats、以及网关 5xx 放在同一块看板上链条一眼就穿起来了。这也是很多 LLM 基础设施团队容易踩的坑LiteLLM 本身是“模型层的东西”Redis 是“缓存层的东西”运维习惯上会把它们分开看但生产环境里它们早就是强绑定关系了。2. 级联故障链路拆解Redis 在 LiteLLM 架构里到底承压在哪2.1 从架构说起LiteLLM 这条路为什么要架一个 Redis先讲清楚一个基本问题LiteLLM 单实例跑的时候限流计数、响应缓存都可以放本地内存完全不需要 Redis。一上生产、一搞多副本情况就变了。K8s 里三个网关 Pod 各自持有独立内存如果限流状态放在各自进程里同一个 API Key 在 Pod A 上已经用完了额度在 Pod B 上还能继续调分布式限流就形同虚设。所以要引入 Redis 作为共享状态层让所有副本读写同一份计数、同一份缓存、同一份运行时配置。这个架构本身没有错同类 LLM 网关比如 one-api也是这个思路。但问题在于共享状态层一旦出故障影响范围就不再是“某个 Pod 的缓存慢了”而是全量副本的请求都在等同一个 Redis。鸡蛋放在同一个篮子里这个篮子一旦出问题炸得会特别快。我在这次事故里体会最深的一点是引入 Redis 解决的问题是“分布式一致性”但引入的故障面是全新的——Redis 的连接数、内存、慢命令、主从切换任何一个环节出问题LiteLLM 都会跟着出问题。而且 LLM 网关的流量模型和普通 API 网关不一样单次请求携带的响应体动辄几千字节这直接放大了 Redis 的内存压力。2.2 内存去向拆解哪些 Redis key 在悄悄吃内存要搞清楚 Redis 为什么被打满先得知道 LiteLLM 在 Redis 里到底存了什么。按我们当时的观测主要有三类第一类是限流计数类 key格式一般是litellm:ratelimit:api_key:model:时间窗口value 很小通常只有一两百字节TTL 等于窗口期加一点余量。这类 key 看起来人畜无害但窗口一多、Key 一分、调用一多数量轻松涨到百万级。第二类是响应缓存类 key格式一般是litellm:cache:prompt_hash:modelvalue 是完整的模型响应。如果业务方用固定 prompt 做问答这类 key 命中率很高是好事但如果调用方每次请求都带随机 trace_id或者 prompt 本身抖动很大缓存 key 的高基数问题就会非常严重——每来一个请求就新建一个缓存条目却几乎没有命中。第三类是业务方自己存进去的“外来户”。我们当时用的 Redis 是和另一个业务团队共用的里面有大量没有设置 TTL 的 key其中有一个 JSON key 的 value 达到了 1.2MB。这类 key 平时不起眼但在 Redis 内存紧张的时候就是压垮骆驼的最后一根稻草。当时抓到的现场数据是这样的# Redis 侧INFO memory / INFO keyspace used_memory: 1784.62M used_memory_rss: 3281.94M maxmemory: 2048M maxmemory_policy: noeviction mem_fragmentation_ratio: 1.84 db0:keys2843012,expires2210432,avg_ttl354avg_ttl354意味着大量 key 很快就要过期但数量实在太大加上无 TTL 的大 value key内存被顶到了上限。再往下看就会发现Redis 的maxmemory_policy是 noeviction也就是内存满了之后直接拒绝写命令——这一步是整个事故的起点。2.3 三个放大器内存告警如何传导成全站故障内存打满本身只是 Redis 的问题它之所以升级成全站故障是因为后面还有三个放大器。第一个放大器是 noeviction 策略下的写入拒绝。Redis 内存触顶后LiteLLM 每次尝试写入限流计数或缓存都会收到OOM command not allowed when used memory maxmemory这个经典报错。我们用的 LiteLLM 版本在 Redis 写失败时没有做好优雅降级异常直接冒到了请求链路里网关开始大面积返回 500 和 429。第二个放大器是业务方的自动重试。OpenAI 官方 SDK 默认就有重试机制一些业务方还自己包了一层高可用逻辑最多重试 5 次退避间隔只有 200ms、400ms、800ms。网关一报错所有调用方几乎同时开始重试重试流量再次打到网关网关又要写 RedisRedis 又拒绝写入错误率被反复拉升形成一个负向反馈循环。第三个放大器是健康检查与 Pod 重启。网关线程池被 Redis 写超时拖住后/health/liveliness探针响应变慢部分 Pod 被杀掉重建。新 Pod 拉起来之后流量被调度到存活副本上单个副本的并发和连接数被瞬间抬高存活副本也开始撑不住雪崩就这么发生了。整条链路拆开来看就是共享 Redis 被业务大 key 和无效缓存顶满内存 → noeviction 策略拒绝写入 → LiteLLM 写限流计数失败 → 请求 500/429 → 客户端 SDK 重试 → 重试流量回到网关和 Redis → 连接数暴涨、线程池阻塞 → 健康检查失败、Pod 重启 → 流量漂移、单副本承压 → 全站故障。3. 应急恢复实录止血操作与降级取舍3.1 我们当时按顺序做的 6 件事故障处理有个原则先止血再定位。我们当时的操作顺序也基本顺着这个逻辑走下来了。第一步打开 Redis 控制台执行INFO memory、INFO keyspace、INFO errorstats确认了 maxmemory 打满和 OOM 报错计数在涨。这一步的核心目的是判断“Redis 是否还有救”如果 errors 在涨但 CPU 不高说明只是内存问题清理 key 就能恢复如果 CPU 已经打满那就可能是慢命令风暴操作要更激进。第二步让业务方临时停掉所有非核心的模型调用。这一步在半夜做有点得罪人但非常有效。把 QPS 降下来之后Redis 的写压力立刻缓解至少能给后续操作争取时间。这里我的经验是不要想着“我们不切流也能修好”生产事故里时间是最贵的资源先降流量永远不亏。第三步用redis-cli --scan --pattern litellm:*抓了一批 key 样本再用MEMORY USAGE找出体型最大的几个。我们当场确认了几类目标那个 1.2MB 的业务 JSON key以及一批 key 数量巨大但命中率几乎为零的响应缓存。对于确认无害的 key直接用UNLINK异步删除避免DEL阻塞 Redis 主线程。第四步把maxmemory-policy从 noeviction 临时改成 volatile-lru。这里要注意改这个配置之后内存不会立刻下降Redis 是在后续写入时才触发逐出检查。但至少它让 Redis 从“拒绝写入”变成了“优先淘汰带 TTL 的 key”给新的写请求腾出了一条活路。第五步在 LiteLLM 侧临时关闭了响应缓存功能。这是个应用层的止损缓存本来就是可丢弃的数据先把这块高频写入停掉Redis 的压力能消掉一大半。关闭后网关配置 reload进程不重启避免再引发一次连接风暴。第六步等网关错误率回落后逐步恢复业务流量先放 10%观察两分钟再放 30%确认稳定后全量恢复。这六步做完距离第一条告警大概过了一个半小时。3.2 为什么不建议第一时间重启 Redis很多人在 Redis 内存爆掉之后的第一反应是“重启一下就好了”这个思路在根因明确前非常危险。重启确实会清空内存里的数据但内存里同时还有 LiteLLM 的限流计数和缓存数据。限流计数一旦清空所有调用方都会被视为“新用户”大量请求瞬间获得放行资格上游模型服务商会被一股脑打过来的洪峰冲垮。另外一个容易被忽略的问题是如果根因没有消除——比如响应缓存还在开、那个没有 TTL 的大 key 还在——重启之后内存会以肉眼可见的速度涨回来等于白操作一次还白白搭上了一次可用性抖动。就算 Redis 开了 RDB 持久化恢复出来的数据也可能再次把内存顶满启动时甚至会因为加载数据触发新一轮的 OOM。我们当天没有重启 Redis就是因为先做了“降流量 清 key 改淘汰策略”这三件事。只有当 Redis 本身出现严重阻塞、不可响应的时候重启才应该进入候选方案。而且重启之前一定要确认上层应用具备重连能力否则你这边 Redis 刚起来LiteLLM 的连接池还停留在旧连接上照样会报错。3.3 fail-open 还是 fail-closed这次事故给我们的教训Redis 挂掉之后网关应该怎么做这次事故暴露了我们默认行为是 fail-closed——Redis 写失败就让请求直接失败。这保证了不会超卖上游额度但也让全站可用性瞬间归零。反过来想如果 fail-open请求会直接放行到模型服务商代价是上游可能被超售打挂。我的结论是不能一刀切。对于限流计数这类“写失败影响的是超额风险”的数据可以 fail-open并在网关本地做一份粗糙的内存计数兜底同时打出告警。宁可短时间超卖也不能让全站不可用。对于鉴权、配额扣减这类强一致数据仍然要 fail-closed因为放行带来的经济损失和合规风险远高于一次 500。这次事件之后我们把 LiteLLM 的 Redis 连接池、读写超时、异常处理路径逐一过了一遍把不同场景下的 fail 策略明文写进了网关配置说明里。技术方案没有绝对的对错但一定要让人在一分钟内能回答出“Redis 挂了网关会怎样”。4. Redis 内存优化与防线重构让网关不再被缓存拖垮4.1 容量规划先算清楚 Redis 到底该给多大Redis 容量规划不能只凭感觉“给个 2GB 吧”要按业务量粗算。我们后来重新梳理了一版估算公式内存预算 日峰值 QPS × 单请求 Redis 写入量 × 窗口 TTL 内保留的请求数系数 × 碎片系数举个例子如果网关峰值 QPS 是 200每次限流写入约 200 字节1 分钟窗口内累计写入 1.2 万次大约 2.4MB1 小时窗口再算一遍大约 144MB。两项相加再乘上 1.2~1.5 的碎片系数大概 200~300MB。如果还开了响应缓存再按“缓存条目数 × 平均响应大小”单独算一批。当时我们最大的问题不是限流 key 太多而是响应缓存 key 膨胀到了百万级每条平均 3~6KB光这一块就吃掉了差不多 1GB 内存。容量规划的另一个要点是给峰值预留足够的缓冲水位maxmemory至少是日常 used_memory 峰值的 1.5 倍并且要盯着used_memory_rss看——used_memory 只是逻辑占用RSS 才是真实的物理内存压力碎片率高了以后 RSS 会远超 used_memory。4.2 TTL 治理与无效缓存识别Redis 内存优化最基础也最见效的一件事就是把 TTL 管起来。所有写入 Redis 的 key 都必须带过期时间这是底线。带 TTL 的 key 即使数量多也会自动滚出去真正打死 Redis 的永远是那些“活到永远的 key”。怎么找无 TTL 的 key生产环境用redis-cli --scan全量刷通常会拖垮 Redis我建议在从节点或者低峰期跑并且用脚本控制采样量。下面这个 Python 脚本的思路可以参考import redis r redis.Redis(decode_responsesTrue) cursor 0 sample [] while True: cursor, keys r.scan(cursorcursor, matchlitellm:*, count500) for k in keys: if r.ttl(k) -1: sample.append(k) if len(sample) 20: break if cursor 0 or len(sample) 20: break print(\n.join(sample))这个脚本每 500 个 key 采样一次拿到 20 个无 TTL 样本就停压力可控。找到问题 key 后用UNLINK异步删除而不是DEL。无效缓存的识别更值得说。我们当时发现响应缓存 key 数量巨大但keyspace_hits极低缓存命中率不到 10%。这说明大部分缓存建了也没人用纯粹在烧内存。这类问题通常出在缓存 key 的生成逻辑上如果调用方在 prompt 里拼了随机数、时间戳、trace_id那么缓存 key 的基数会无限膨胀。解决的思路有两个要么在网关层对 prompt 做归一化处理要么干脆对这类流量关闭缓存。4.3 淘汰策略怎么选noeviction、allkeys-lru 还是 volatile-lruRedis 的maxmemory-policy有几种常见选择生产环境里这不是一个可以随手填的配置策略行为适用场景noeviction内存满后拒绝写入数据强一致场景但容易引发写失败和级联故障allkeys-lru全空间按 LRU 淘汰纯缓存场景不区分是否有 TTLvolatile-lru只淘汰带 TTL 的 keyLiteLLM 这类大部分 key 带 TTL 的场景volatile-ttl优先淘汰剩余时间最短的 key对数据新鲜度有要求我们最终在恢复阶段选择了 volatile-lru核心考虑是LiteLLM 的限流计数和响应缓存本来就带 TTL属于“可以牺牲、可以重建”的数据而无 TTL 的业务大 key 虽然坑但不应由 Redis 自动淘汰。volatile-lru 能把淘汰范围限制在带 TTL 的数据里保住无 TTL 的“硬数据”。需要提醒的是淘汰策略是兜底不是第一道防线。如果内存经常触发淘汰说明容量规划已经失效了该扩容就扩容该治理就治理。别把allkeys-lru当成万能药它会导致所有 key 都可能被牺牲包括一些不应丢失的数据。顺便说一下碎片。我们当时的mem_fragmentation_ratio是 1.84说明大量短 TTL key 频繁创建、销毁内存碎片非常严重。可以在 Redis 配置里开启activedefrag yes让 Redis 在后台自动整理碎片如果碎片率持续超过 1.5还伴随 RSS 暴涨就要考虑重启实例或者迁移数据了。4.4 实例隔离与连接参数这次事故最深刻的结论之一就是共享 Redis 是定时炸弹。LiteLLM 的限流计数写得很频响应缓存动不动上 GB这两类数据都不适合和一个陌生业务共享同一个实例。事后我们把 Redis 拆成了两层核心的 LiteLLM 状态用独立实例业务缓存走另一个集群彼此之间互相隔离。如果实在做不到实例隔离退一步也要做到“逻辑隔离 配额配额”。用不同的 db 编号分隔同时给每个业务设置明确的 key 前缀约定比如litellm:*、biz:xxx:*这样至少可以通过INFO keyspace和--scan快速定位是哪一方的 key 在膨胀。连接参数也非常关键。LiteLLM 连接 Redis 时connect_timeout、socket_timeout、max_connections 这些参数不能全走默认值。我们当时的问题之一就是连接池过小Redis 写慢的时候请求全部堵在池子里等连接线程池被占满。建议把 socket_timeout 调到一个较小的值比如 2 秒宁可让单一请求快速失败走降级也不能让一堆请求无限阻塞在 Redis 连接上。高可用方面生产环境至少要有主从哨兵或者直接用云上托管 Redis。主从切换这个动作本身也会造成几十秒的不可用LiteLLM 侧要做好自动重连和重试。我们暂时还没做到完全无感切换但这已经是下一步明确要补的功课。4.5 监控告警这样做才算到位这次事故之后我把 Redis 相关监控重新梳理了一遍。Redis 侧最重要的几个指标是used_memory / maxmemory超过 80% 告警、evicted_keys持续大于 0 要告警、rejected_connections连接数触顶、blocked_clients客户端被阻塞、connected_clients突增说明流量异常、instantaneous_ops_per_sec每秒命令数、INFO commandstats里的usec_per_call慢命令指标。LiteLLM 侧要盯的是5xx 比例、p95 延迟、限流命中次数、缓存命中率。特别是缓存命中率它直接反映了响应缓存有没有在干活。如果缓存命中率走低而缓存 key 数量走高说明在烧内存换空气该处理了。王炸级别的操作是把这些指标放到同一块看板上。我们这次走弯路的原因就是 Redis 看板归 Redis、网关看板归网关两边没叠在一起。后来我把 Redis 内存、evicted_keys、LiteLLM 5xx 曲线画成同一条时间轴的关联图再遇到类似情况一分钟就能定位到是哪一边先出的事。5. 复盘沉淀排查工具与避坑清单5.1 Redis 侧排查命令速查踩过一次坑之后我把常用的 Redis 排查命令整理成了一个速查表贴在了团队文档里目的命令注意点看内存与配置INFO memory关注 used_memory_rss、maxmemory、mem_fragmentation_ratio看 key 数量与 TTL 概览INFO keyspace对比 keys 和 expires差值就是无 TTL key 的近似量看错误类型统计INFO errorstats能直接看到 OOM 类错误计数Redis 6.2找大 keyredis-cli --bigkeys尽量在从节点跑避免拖慢主实例看单个 key 内存占用MEMORY USAGE key定位具体大 value看慢命令SLOWLOG GET关注高耗时写入命令看热点 keyredis-cli --hotkeys需要开启 LFU 淘汰策略默认不可用异步删除大 keyUNLINK key不要用 DELDEL 会阻塞主线程这里特别说一句MONITOR命令虽然能看到所有实时命令但生产环境千万别随便开。它会显著降低 Redis 吞吐曾经有人开着 MONITOR 排查问题结果自己把 Redis 拖垮了。5.2 写进作战手册的应对流程事故复盘如果不落到流程上下次大概率还会换个姿势再踩一遍。我们把这次事件抽成了一个标准应对流程写进了运维作战手册确认影响面拉出 Redis 内存、网关 5xx、Pod 重启数的关联图快速判断是单点故障还是级联故障。降流量让非核心调用方先停手把 QPS 降到安全水位。看 Redis 指标优先看INFO errorstats、evicted_keys、SLOWLOG GET判断是内存问题还是慢命令问题。定位大 key用--scanMEMORY USAGE找到可疑目标确认无害后UNLINK。止血调整按情况调整maxmemory-policy、关闭不必要的缓存、临时扩容实例规格。观察恢复错误率回落、延迟恢复正常后才逐步放流量不要一次全量恢复。复盘归档写清楚时间线、决策点、依据和遗留改进项。这个流程看起来简单但每条背后都有代价。第 2 步“降流量”我们当时执行得不够果断结果第 5 步怎么调都稳不住。现在我们把“是否降流量”的决策权下放给了值班同学不需要等 leader 拍板。5.3 一些常规文档不会写的经验最后分享几条比较“私人”的经验。第一条先处理 Redis再质问业务方。共享 Redis 里经常躺着别人的 key内存爆了之后很容易互相甩锅。但无论这个 key 是谁的第一要务是先让 Redis 恢复写入能力恢复可用性之后再去清理业务关系和约定边界。生产事故现场不是追责的场合。第二条看内存不要只看 used_memory一定要看 RSS。我们这次 used_memory 才 1.78GB但 RSS 已经 3.2GB碎片就让物理内存压力翻了一倍。如果只看逻辑内存你会觉得“2GB 上限还有 200MB 余量”但实际上机器早就吃紧了。第三条改动 Redis 配置之前必须确认主从同步和配置文件持久化。用CONFIG SET临时改的 maxmemory-policy如果不写进配置文件下次重启就回到旧值等于白改。我当时改完之后特意确认了持久化才放心继续后面的操作。第四条LiteLLM 这类 LLM 网关是相对较新的基础设施故障模式还没被广泛认知别指望社区文档把踩坑经验都写全。多花点时间做混沌演练把 Redis 内存打满、Redis 宕机、连接池打爆这些场景在预发环境提前跑一遍比事后复盘省钱得多。踩过这次坑之后我现在看到 Redis 内存告警的心态完全变了。以前第一反应是扩容现在第一反应是打开INFO keyspace看还有多少 key 带着 TTL用MEMORY USAGE抓几个大户先搞清楚这些内存是“该花的”还是“泄漏的”。扩容能解决一时但每次故障背后都有一个“为什么会涨成这样”的答案。希望这篇复盘能帮你少踩一个坑。