Redis XTRIM MINID 怎样按消息 ID 清理 Stream

使用 XTRIM stream_key MINID = cutoff_id，可以清理 ID 严格小于 cutoff_id 的 Stream 消息；等于阈值的消息保留。MINID 自 Redis 6.2 起可用。它比较的是 Stream ID，不读取消息字段里的业务时间，也不会自动判断所有消费者是否已经处理完成。

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

我会把这个任务当成一次数据保留决策：既要控制 Stream 大小，也要保住消费恢复与业务回放需要的内容。下面的订单事件只是独立测试示例，没有真实订单数据，也不代表已执行的线上清理。

先保护哪几类数据？

清理涉及三个不同对象：Stream 消息正文、消费者组的 PEL 待确认引用，以及业务端依赖的回放数据。它们不能用一个“消息已过期”结论一起处理。正文被裁剪后，保留下来的待确认引用并不使正文重新存在；后续恢复消费时可能面对消息内容缺失。

我的底线是先确认回放承诺。如果业务需要重放较早的事件，阈值必须服从这项需求，或者先有独立且可用的归档。消费者确认状态也是清理条件的一部分，而不是看到 Stream 很长便先裁掉再说。

阈值最容易在哪些地方算错？

Stream ID 由毫秒部分和序列部分组成，比较时要保留完整含义。例如阈值 2000-1 会覆盖更小的 2000-0；阈值 2000-0 则保留同一毫秒下的 2000-0、2000-1。不要在应用里用普通字符串字典序代替 ID 的数值分量比较。

自动生成 ID 的毫秒部分与 Redis 生成 ID 时的时间机制有关，但它不等于事件字段中的发生时间。补录旧事件、显式指定 ID、延迟投递等情况都可能使两者不同。若保留规则依据业务事件时间，需要另外设计索引或清理方案，不能直接从 MINID 推出正确结果。

先用独立样本确认精确清理边界

以下 Bash 命令通过 redis-cli 连接本地独立测试实例。先确认示例键不存在，再逐条执行；不要把键名替换成生产 Stream 后整段运行。实际连接参数由测试环境决定，不要把密码写进脚本或日志。

# 只在独立测试实例检查演示键；预期应不存在，否则更换示例键。
redis-cli EXISTS demo:retention:minid

# 假设这是全新键，用显式ID表达严格大小关系；并非真实时间戳样本。
redis-cli XADD demo:retention:minid 1000-0 kind created
redis-cli XADD demo:retention:minid 2000-0 kind checked
redis-cli XADD demo:retention:minid 2000-1 kind packed
redis-cli XADD demo:retention:minid 3000-0 kind shipped

# 清理前观察消息；本示例没有消费者组。
redis-cli XRANGE demo:retention:minid - +

# 精确清理严格小于2000-0的消息，保留阈值本身。
redis-cli XTRIM demo:retention:minid MINID = 2000-0

# 清理后读取消息ID与长度，确认边界而不只看返回的删除数量。
redis-cli XRANGE demo:retention:minid - +
redis-cli XLEN demo:retention:minid

在这组全新、无并发写入的样本中，按规则只有 1000-0 应被移除，其余三个 ID 应保留。这是预期结果说明，并非本机运行记录。XTRIM 返回移除条数，不是剩余长度，也不是命令耗时。

我更看重阈值附近的几条消息是否符合约定，因为“删了很多条”并不能说明删对了。线上还要考虑并发写入，前后长度差不一定等于本次删除量，不应只用这个差值断定命令异常。

近似模式和消费者组策略分别限制什么？

精确模式使用 =，不写操作符时也默认精确。近似模式使用 ~，倾向于以更高效的内部节点单位回收，可能保留一些低于阈值的消息。小 Stream 上返回 0 并不一定是阈值写错，也可能暂时没有可整块回收的内容。

# 供已选择近似清理的场景参考；引号避免shell把波浪号特殊解释。
# LIMIT限制检查工作量，不是保证删除500条或耗时上限。
redis-cli XTRIM demo:retention:minid MINID '~' 2000-0 LIMIT 500

LIMIT 应与近似模式配合使用。增加检查限额不保证近似模式立刻达到严格边界；如果必须按 ID 精确清理，需要选精确模式并评估单次处理规模，不能把“限额”误当作精准批处理条数。也不建议为了得到一个非零返回值，在定时任务里无限快速重试。

Redis 8.2 起可显式选择 KEEPREF、DELREF 或 ACKED。KEEPREF 默认保留 PEL 引用，但消息仍按阈值清理；DELREF 同时移除相关引用；ACKED 限制为所有消费者组都已读取并确认的消息。没有消费者组时，这些选项不发挥作用。

这些策略解决的是不同问题。若目标是保护慢消费者，保留引用并不够；若使用 ACKED，也要接受符合 ID 条件但未满足全组确认条件的消息继续保留。旧版本不能直接照搬新选项，部署前要确认服务端与客户端支持。本文基础样本省略引用选项，以便专注演示 Redis 6.2 起的 MINID 语义。

把误删风险落到权限与审计上

对于定时清理，我会把键范围、阈值来源、允许推进幅度和引用策略放在明确配置中。不要直接接收外部请求提供的任意键和阈值。清理账号应只获得任务所需的命令与键范围权限；键名前缀也不能只靠应用注释约定。

每次任务记录目标实例标识、键名、阈值、精确或近似模式、检查限额、引用策略、移除数量和执行错误。不要记录完整消息正文、连接凭据或含敏感信息的字段。阈值计算异常时应停止推进并报告，而不是用最大 ID 代替缺失配置。

XTRIM 没有通用的撤销命令。清理前如果依赖归档恢复，就应明确归档在哪里、是否覆盖本次范围、恢复会如何影响消费者组。仅仅声明“Redis 开了持久化”不能当作本次误删自动可恢复的保证。

能按“保留七天”直接给 MINID 一个秒数吗？

不能。参数是消息 ID 阈值，不是相对时长。只有当业务接受 ID 时间近似代表保留时间时，才由任务计算截止毫秒并构造完整 ID，同时处理时钟与补录语义。

PEL 不为空就绝对不能清理吗？

取决于业务是否允许丢弃这些消息。若要求恢复所有未确认处理，必须先保护对应正文；若明确允许过期丢弃，也要有匹配的引用处理和消费端行为，不应让默认参数替业务作决定。

验收只看 XLEN 下降够不够？

不够。至少核对阈值附近 ID、消费者恢复行为、回放需求和任务审计。近似模式允许旧消息残留，精确清理也不证明消费者已经处理。我的选择是先把这些条件写清，再决定清理频率和批量。

# 仅删除本次独立演示键；确认环境与键名后执行。
redis-cli DEL demo:retention:minid

参考：Redis XTRIM 参数和引用策略、Redis XADD 与消息 ID。