Redis Stream 怎样按最小 ID 裁剪历史

我在给事件流做保留策略时，最容易先想到的是 MAXLEN：超过多少条就删多少条。但如果真正的要求是“只保留最近一段时间”，条数并不稳定，流量一高，同样的 10 万条可能只覆盖几分钟。Redis Stream 可以用 XTRIM key MINID threshold 删除低于某个 ID 的历史条目；因为 Stream ID 的前半段通常是毫秒时间，所以它很适合表达一个时间近似的截止线。

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

Redis Stream 的 ID 如何变成 MINID 截止线

Stream 的自动 ID 形如 1692632147973-0：短横线前是毫秒级时间部分，后面是同一毫秒内的序列号。它不是业务时间戳字段，也不等于跨多个 Stream 的全局时钟，但在一个 Stream 内是按顺序增长的。我的做法是先把保留窗口换算成毫秒截止值，再拼成 cutoff_ms-0。

# 写入两条示例事件；* 让 Redis 自动生成 Stream ID
redis-cli XADD orders:events * type order.created order_id o-1001
redis-cli XADD orders:events * type order.paid order_id o-1001

# 例：cutoff_ms 来自“当前时间减去保留窗口”，只保留该 ID 及之后的条目
redis-cli XTRIM orders:events MINID 1720000000000-0

# 用最早和最新 ID 复查保留边界；这里是读取示例，不代表本机运行结果
redis-cli XRANGE orders:events - + COUNT 10

阈值写成 1720000000000-0 时，同一毫秒内序列号为 0 的 ID 已经是边界。低于这个完整 ID 的记录会被裁掉，等于或高于它的记录保留。为了不把图示误认为运行证据，下面的图片只画 ID、截止线和保留条目的结构关系。

按时间窗口还是按条数，先看保留压力

我第一次使用 Stream 裁剪时，曾把“最近一小时”和“最多十万条”当成同一个要求。它们其实是两种不同的架构压力：前者关心事件新旧，后者关心内存上限。Redis 官方把 MINID 定义为删除低于 ID 阈值的条目，把 MAXLEN 定义为在流长度超过阈值时删除最旧条目。

如果下游说的是“审计数据至少保留 24 小时”，我会优先算 MINID；如果下游只需要“最近 50 万条事件”，我会优先用 MAXLEN。两者可以在写入或定时任务中组合，但要先写清楚哪个是硬边界，避免一条规则把另一条规则的意图冲掉。

精确裁剪与近似裁剪怎么落地

XTRIM 默认执行精确裁剪，也可以显式写 =；写 ~ 则允许 Redis 为效率保留略多于阈值的条目。我的经验是：定时批量清理通常优先 ~，因为它不必让每次写入都承担精细删除；需要明确的边界检查或小流量测试时，再使用精确形式。

# 精确按最小 ID 裁剪：低于阈值的条目全部进入删除范围
redis-cli XTRIM orders:events MINID = 1720000000000-0

# 近似按最小 ID 裁剪：允许暂时保留少量额外条目，通常更适合周期任务
redis-cli XTRIM orders:events MINID ~ 1720000000000-0

# 精确按数量裁剪：最多保留 100000 条最新事件
redis-cli XTRIM orders:events MAXLEN = 100000

# 近似按数量裁剪：以数量为目标，但允许略超出
redis-cli XTRIM orders:events MAXLEN ~ 100000

命令返回被删除的条目数量。不要把返回值当成“仍然保留了多少条”：需要知道当前条数时，另用 XLEN 查询。对于近似裁剪，复查时应接受短时间内的偏差，而不是把它误判为命令失效。

生产里最容易忽略的三个后果

第一，MINID 的毫秒部分是保留线索，不是完整的业务时间证明。如果事件来自延迟生产、手工指定 ID 或多个生产者，仍要把业务发生时间放在字段里，裁剪任务只负责 Stream 的存储窗口。

第二，重复执行同一条 MINID 是幂等方向的：第一次删掉低于阈值的条目，下一次通常没有同一批旧条目可再删。定时任务应记录 cutoff、策略、是否带 ~ 和删除数量，排障时才能区分“没有旧数据”和“任务根本没执行”。

第三，裁剪和消费确认不是一回事。Stream 如果被消费组读取，还应同时关注组的 pending、lag 和重放需求；本文的 MINID/MAXLEN 只解决历史保留，不自动替你判断某条消息是否已经被业务处理。

我的判断清单

• 需求是时间窗口：计算毫秒 cutoff，优先选择 MINID，并保留业务时间字段。
• 需求是内存或重放条数上限：选择 MAXLEN，明确 exact 或 approximate。
• 任务是周期清理且允许小幅偏差：使用 ~，并以 XLEN 和删除数量做监控。
• 存在消费组：裁剪前检查 pending、lag 和业务重放窗口，不把裁剪结果当作 ACK。

常见问题

MINID 的阈值为什么常写成时间戳加 -0？

因为 Stream ID 由毫秒部分和序列号组成，写成 cutoff_ms-0 可以表达从这个毫秒边界开始保留。它是按 Stream ID 排序的保留线，不是业务时间字段的替代品。

MINID 和 MAXLEN 能不能同时使用？

可以分别在写入或维护任务中承担不同约束，但要明确优先级。时间保留与数量上限是两种不同目标，组合时应记录每次实际删除数量和当前长度。

用了波浪号却看到条数超过阈值，是不是失败？

不一定。~ 表示近似裁剪，允许略多于阈值以降低精确维护成本。只有在必须严格满足边界时，才用不带波浪号的精确形式。