增量去重机制：使用Redis HyperLogLog统计机器人UV与去重

Telegram 机器人在实际运行中，经常会因为回调重试、用户重复点击、网络波动或多端操作产生大量重复事件。如果直接按照消息数量统计访问量，结果往往会严重偏高，无法准确回答“今天到底有多少个独立用户使用过机器人”这个问题。

Redis HyperLogLog 提供了一种适合高并发场景的近似去重统计方案。它不保存完整用户名单，却能用极低的内存估算 UV，特别适合 Telegram 机器人、活动落地页、频道推广和接口访问量统计。

🎯 一、先理解增量去重与 UV 统计

UV 是 Unique Visitor 的缩写，表示在指定时间范围内访问过系统的独立用户数量；PV 则是访问或事件总次数。同一个用户连续发送十条消息，通常应当只计为一个 UV，但会产生十次事件记录。

所谓增量去重，就是每当机器人收到一个事件，就把经过标准化处理的用户标识写入当天的 HyperLogLog，随后持续读取估算结果，而不是每次都查询完整用户列表。

UV(日) = 指定日期内所有独立 visitor_id 的基数
写入：PFADD tg:uv:20250308 visitor_id
统计：PFCOUNT tg:uv:20250308

这种设计的核心价值是把高频写入和低成本统计结合起来。机器人只需要处理一个短字符串，而 Redis 负责维护基数估算结构，避免使用大型 Set 保存数百万个原始用户 ID。

🧠 二、Redis HyperLogLog 的工作机制

HyperLogLog 会对输入值进行哈希，再根据哈希结果更新内部寄存器。Redis 不需要保存每个用户的原始值，因此可以在固定且很小的内存占用下，估算集合中不同元素的数量。

PFADD 用于向 HLL 添加一个或多个元素，PFCOUNT 用于读取基数，PFMERGE 则可以把多个日期或多个来源的 HLL 合并成一个集合。

PFADD tg:uv:20250308 user_1001
PFADD tg:uv:20250308 user_1001 user_1002

PFCOUNT tg:uv:20250308

PFMERGE tg:uv:month:202503 tg:uv:20250301 tg:uv:20250302
PFCOUNT tg:uv:month:202503

📌 PFADD 返回值能否作为“首次访问”判断？

PFADD 返回 1，表示内部寄存器发生了变化；返回 0，表示本次写入没有让估算结构发生变化。这个返回值可以作为“可能是新访客”的提示，但不能等同于精确去重结果。

因此，PFADD 的返回值适合用于日志采样、首次访问比例等统计，不适合直接触发优惠券发放、积分奖励或一次性权益。需要强一致判断时，应使用 Redis Set、数据库唯一索引或专门的幂等键。

📊 误差与内存边界

Redis HyperLogLog 的标准误差约为 0.81%，实际结果是统计意义上的估算值，而不是绝对精确值。例如真实 UV 为十万时，理论标准误差规模约为八百左右。

单个 HLL 在密集存储状态下最多约占 12KB，稀疏数据时通常更小。最终内存还取决于日期维度、机器人数量、渠道数量和保留周期，因此上线前仍应通过压测确认。

🧩 三、设计可靠的 Key 与用户标识

推荐按照“业务类型、机器人、日期”设计 Key，例如每天为每个机器人创建一个独立 HLL。日期最好统一使用 UTC 或业务所在时区，避免服务器时区不一致导致数据被写入错误的统计周期。

tg:uv:{bot_123}:20250308
tg:uv:{bot_123}:20250309
tg:uv:month:{bot_123}:202503

在 Telegram 机器人中，已登录用户可以优先使用 Telegram user_id 作为逻辑标识；但不建议把原始 ID 直接写入日志或跨系统传播。更稳妥的方式是使用带服务端密钥的 HMAC，将用户标识转换为不可逆的伪名。

visitor_id = HMAC_SHA256(server_secret, bot_id + "|" + telegram_user_id)

不要简单使用 IP 地址作为唯一访客标识，因为移动网络、代理和企业网络会让多个用户共享 IP。对于匿名访问，可以结合短期会话 ID，并遵循最小化收集原则，同时明确数据保留时间和使用目的。

🗓️ 日统计、月统计与生命周期

日 UV 应写入日级 Key，月 UV 则通过多个日级 HLL 合并得到。合并时，重复出现在不同日期的用户只会在基数中计算一次，这正是 HLL 适合统计周期 UV 的原因。

日级 Key 可以设置 60 至 90 天的过期时间，月级报表则根据财务或运营需求单独保留。设置过期时间时不要在每次请求中无条件刷新 TTL，否则活跃机器人可能让旧 Key 长期不释放。

⚙️ 四、Node.js 中实现增量 UV 记录

下面示例使用 Redis 原生命令完成写入，并通过 TTL 判断是否需要补充过期时间。业务代码应先校验 bot_id 的格式，避免外部输入直接拼接成不可控的 Redis Key。

import { createHmac } from 'node:crypto';

async function recordUv(redis, botId, telegramUserId, eventAt = new Date()) {
  const day = eventAt.toISOString().slice(0, 10).replaceAll('-', '');
  const visitorId = createHmac('sha256', process.env.HLL_SECRET)
    .update(`${botId}|${telegramUserId}`)
    .digest('hex');

  const key = `tg:uv:{${botId}}:${day}`;
  const changed = Number(
    await redis.sendCommand(['PFADD', key, visitorId])
  );

  const ttl = Number(await redis.sendCommand(['TTL', key]));
  if (ttl === -1) {
    await redis.expire(key, 90 * 24 * 60 * 60);
  }

  return { maybeNew: changed === 1, key };
}

这里的 maybeNew 只代表 HLL 内部可能发生了变化，不能作为绝对准确的首次访问标记。统计接口可以在定时任务中批量执行 PFCOUNT，避免每一条机器人消息都立即读取 UV。

如果 Redis 使用 Cluster，参与 PFMERGE 的 Key 必须落在同一个哈希槽。示例中的花括号是 Redis Hash Tag，能够让同一机器人相关的日 Key 和月 Key使用相同的槽位。

🛡️ 五、生产环境中的准确性与安全性

🔁 处理重试与重复事件

Telegram 更新事件可能因为响应超时而被重复投递，因此业务层应根据 update_id 或自定义事件 ID 做幂等处理。即使重复执行 PFADD，也不会像普通计数器那样把同一个用户重复累加。

🎯 选择正确的去重工具

HyperLogLog 适合回答“有多少独立用户”，不适合回答“某个用户是否存在”或“列出所有访问者”。需要查询成员、删除成员或执行精确奖励时，应使用 Set 或数据库；需要低延迟判断事件是否处理过时，可以使用带 TTL 的幂等键。

📈 建立可验证的监控

建议监控 PFADD 写入错误、Redis 内存、Key 数量、TTL 是否缺失以及日 UV 的异常波动。上线初期可以抽取小流量，用 Set 进行精确统计，再与 HLL 结果对比，确认误差符合业务预期。

当 UV 突然暴涨时，不要立刻认定是营销成功，也可能是爬虫、恶意请求或 visitor_id 生成逻辑改变。把原始事件计数、有效用户数、来源渠道和错误率放在同一看板中，才能完成有效诊断。

❓ 常见问题解答（FAQ）

1. HyperLogLog 统计的 UV 是精确值吗？

不是，它是带有统计误差的近似基数。对于趋势分析、渠道对比和运营报表通常足够，但合同结算、财务分账等场景应采用精确数据结构。

2. 为什么 PFADD 返回 0，但用户可能是新用户？

因为 PFADD 的返回值反映的是寄存器是否变化，而不是对输入值执行精确成员查询。即使输入值之前没有出现，也可能因为哈希碰撞或寄存器状态而返回 0。

3. HyperLogLog 可以删除某个用户吗？

不能单独删除某个成员，因为 HLL 不保存可枚举的原始用户集合。如果需要满足删除请求，应保留独立的精确数据索引，或者通过缩短 HLL 保留周期和重新计算来降低数据留存范围。

4. 日 UV 能直接相加得到月 UV 吗？

不能直接相加，因为同一用户可能在多天访问。正确做法是使用 PFMERGE 合并日级 HLL，或者对多个日 Key 执行 PFCOUNT，从而自动消除跨日重复用户。

5. Telegram user_id 是否可以直接作为统计标识？

技术上可以，但从隐私和数据治理角度，更推荐使用服务端密钥生成 HMAC 结果。这样既能保持同一用户在不同事件中的一致性，也能避免在日志、报表和第三方系统中暴露原始标识。