Redis XTRIM 怎样限制 Stream 长度

如果 Redis Stream 只写不清理，消息量增长后，内存占用和遍历成本都会跟着上升。限制长度最直接的办法是使用 XTRIM 的 MAXLEN：它按照 Stream 的消息数量删除较旧条目，只保留较新的部分。

我在实际写入链路里通常会优先考虑下面这一条命令：

# 让 mystream 最多保留约 1000 条，优先控制写入路径的额外开销
redis-cli XADD mystream MAXLEN ~ 1000 * event login user_id 42

其中 ~ 表示近似裁剪，Stream 可能暂时多保留一些条目，但它通常比每次都做严格精确裁剪更省工作量。如果业务必须把长度压到明确阈值，再去掉 ~ 使用精确裁剪。

Redis 官方地址：https://redis.io/docs/latest/commands/xtrim/

我先把“限制长度”拆成两个动作

XTRIM key MAXLEN threshold 的含义不是给 key 设置一个类似过期时间的属性，而是立刻对已有 Stream 做一次裁剪。MAXLEN 的阈值表示裁剪后最多希望保留多少条，Redis 会优先删除 ID 更小的旧消息。

例如 Stream 当前有 1500 条消息，希望只留 1000 条，可以写成：

# 不带 ~ 时执行精确裁剪，目标是让长度降到阈值
redis-cli XTRIM mystream MAXLEN 1000

# 返回值表示本次从 Stream 中删除的条目数
redis-cli XLEN mystream

这里的两个返回值要分开理解：XTRIM 返回的是本次删除了多少条，XLEN 返回的是当前 Stream 长度。不要把裁剪命令的返回值直接当成裁剪后的总长度。

精确裁剪和近似裁剪怎么选

这一步是最容易写错的地方。两种语法看起来只差一个字符，但对应的工程取舍不同：

如果 Stream 用作短期事件缓冲区，我一般选近似裁剪。它的价值不是“永远正好 1000 条”，而是允许 Redis 以更低的裁剪成本维护一个接近 1000 的范围。若下游逻辑要求每次读取都不能超过固定条数，应该在读取端使用明确的读取数量，不要把近似裁剪当成读取分页限制。

# 高频事件场景：允许保留少量额外条目，减少严格裁剪的开销
redis-cli XTRIM event-stream MAXLEN ~ 50000

# 报表快照场景：需要明确的长度边界时使用精确裁剪
redis-cli XTRIM snapshot-stream MAXLEN 2000

把裁剪接到 XADD 写入路径

如果只定时执行独立的 XTRIM，两个清理周期之间仍然会出现增长峰值。对持续写入的 Stream，更实用的方式是把 MAXLEN 放到 XADD 中，让每次写入顺便执行裁剪：

# 写入新事件，同时让 Stream 维持在接近 10000 条的范围
redis-cli XADD order-events MAXLEN ~ 10000 * order_id 9001 status paid

# 写入完成后查看当前长度；它可能略高于 10000，这是 ~ 的正常语义
redis-cli XLEN order-events

这种方式的关键是把“保留策略”与“写入入口”放在一起维护。以后如果有多个生产者，不要让每个生产者使用不同阈值；最好把 Stream 名称、阈值和精确/近似选择收敛到一个配置或封装方法中。

LIMIT 能解决什么问题

LIMIT count 用来限制一次裁剪中最多检查或淘汰的条目数量，尤其适合和近似裁剪一起使用。它可以把单次清理的工作量切小，但也意味着一次命令结束后，Stream 可能还没有达到目标长度。

# 每次最多处理一小段，避免单次裁剪占用过多时间
redis-cli XTRIM event-stream MAXLEN ~ 50000 LIMIT 2000

# LIMIT 0 表示不启用这个数量限制，使用前要确认业务能接受单次工作量
redis-cli XTRIM archive-stream MAXLEN ~ 100000 LIMIT 0

因此，LIMIT 不是“保证裁剪后长度等于阈值”的参数。如果你需要严格收敛到阈值，应先明确是否可以接受精确裁剪的成本，再决定是否省略 LIMIT。如果只关心吞吐和内存增长趋势，近似裁剪配合适当的处理上限通常更稳妥。

消费组引用不是 Stream 长度

Stream 的条目、消费组的已读位置和 PEL（Pending Entries List）是不同层次的数据。执行 XTRIM 只是在 Stream 中移除符合策略的条目，不能替代消费组的确认、重试或积压治理。

在没有消费组时，重点是消息保留数量和生产者吞吐；使用消费组后，还要明确旧消息被裁剪时，消费组引用如何处理。Redis 官方文档提供了 KEEPREF、DELREF 和 ACKED 等引用策略，具体可用项取决于部署版本。

# 只演示参数形状：裁剪前先确认目标 Redis 版本支持引用策略
# KEEPREF 保留消费组 PEL 中已有的引用关系
redis-cli XTRIM order-events MAXLEN ~ 10000 KEEPREF

# 读取当前长度，不能用它判断消费组是否已经处理完消息
redis-cli XLEN order-events

如果业务要求“每条消息都必须被消费后才能删除”，单独设置 MAXLEN 并不能满足这个要求。此时需要把确认策略、失败重试、积压监控和裁剪策略一起设计，否则 Stream 变短了，未处理消息也可能已经失去保留窗口。

我的选择结论：先保证增长受控，再讨论严格边界

对大多数高频事件 Stream，我会从 XADD ... MAXLEN ~ N 开始，把它作为写入路径的一部分；对条数必须严格受控的短列表，使用独立的精确 XTRIM，并把删除数记录下来。只有在确实需要控制单次裁剪工作量时，才增加 LIMIT。

可以按下面的顺序做决策：

1. 先确认要限制的是消息数量，还是按消息 ID 保留时间窗口；前者用 MAXLEN，后者可以考虑 MINID。
2. 只要允许少量超出阈值，就优先考虑 ~；不能接受超出时才使用精确裁剪。
3. 让所有写入者共享同一套保留参数，避免同一个 Stream 出现多个长度策略。
4. 如果有消费组，把 Stream 条目裁剪和 PEL、确认、重试分别监控。

常见问题

XTRIM MAXLEN 会删除最新消息吗？

正常的 MAXLEN 裁剪会优先删除 ID 更小的旧消息，保留较新的条目。它不是随机删除，也不是从尾部截断。

为什么执行 MAXLEN ~ 1000 后仍然超过 1000 条？

因为 ~ 明确允许近似裁剪，Redis 可能为了减少额外工作而暂时保留一些条目。需要严格阈值时，改用不带 ~ 的精确形式。

用 XTRIM 后，消费组就不会丢消息了吗？

不是。XTRIM 负责 Stream 条目的保留策略，消费组确认、PEL 和重试是另一组机制。要不要保留已被消费组引用的条目，需要结合部署版本和引用策略单独设计。

一句话总结：MAXLEN 解决的是 Stream 会不会无限增长，~ 解决的是裁剪成本与严格边界之间的取舍，而消费组可靠性不能只靠长度裁剪来保证。