Hyperf中用Redis Bitmap统计在线用户需绕过key序列化并校验offset合法性：用$this->redis->setBit()而非opsForValue().setBit()，用户ID须转为非负整型offset，统计用bitCount()。
Hyperf 中用 Redis Bitmap 统计在线用户，核心是把用户 ID 当作 offset，用 SETBIT 和 GETBIT 控制状态，再用 BITCOUNT 实时查总数 —— 但直接套用 redisTemplate.opsForValue().setBit(key.getBytes(), offset, true) 会统计不准，关键在 key 的序列化方式。
Hyperf 里 setBit 统计为 0？检查 key 是否被自动序列化
Hyperf 默认使用 RedisTemplate（或 Hyperf\Redis\Redis）时，opsForValue().setBit(key, offset, true) 会把 key 按 JDK 序列化规则转成字节数组，而底层 Redis 命令 SETBIT 期望的是原始字符串 key。两者不一致，导致 BITCOUNT 查不到数据，始终返回 0。
- ✅ 正确做法：绕过序列化，用原生连接执行命令，例如：
$this->redis->executeRaw(['SETBIT', 'online_users', $uid, 1]) - ⚠️ 注意：Hyperf 的
Redis组件默认不支持executeRaw直接传数组，需改用eval或封装连接对象；更稳妥的是用$this->redis->setBit('online_users', $uid, true)—— 这个方法内部已处理原始 key 字符串，不走序列化 - ❌ 错误写法：
$this->redis->getRedis()->setBit('online_users', $uid, true)（如果调用的是 Predis 或 phpredis 原生客户端，可能仍走序列化）
用户登录/登出时怎么安全更新位图
Bitmap 是纯二值结构，没有原子性“判断再设置”，所以并发登录/登出时可能出现状态错乱。不能只依赖 SETBIT，得加一层幂等控制。
- 登录时：先
GETBIT online_users $uid判断是否已是 1，避免重复写入（虽不影响结果，但减少无谓网络开销） - 登出时：直接
SETBIT online_users $uid 0即可，无需判断 —— 写 0 是幂等的 - 超时下线建议：不依赖定时任务扫库，改用登录时设置 key 过期（
EXPIRE online_users 86400），或用单独的zset记录最后活跃时间做兜底
统计实时在线人数必须用 BITCOUNT，别用 KEYS + SCAN
有人想用 KEYS online_users* 扫多个分片 key 再累加，这是典型误区。Bitmap 的优势就在于单 key 内 O(1) 统计，BITCOUNT 时间复杂度是 O(N/8)，N 是最大 offset，实际非常快（亿级用户也只要毫秒级）。
- ✅ 推荐：
$count = $this->redis->bitCount('online_users')—— 返回当前所有为 1 的 bit 数，即在线用户数 - ⚠️ 避免：
SCAN遍历 key、或用HLEN/SCARD等其他结构模拟，内存和 CPU 开销都高几个数量级 - ? 扩展场景：如需统计“最近 1 小时上线用户”，可另存一个 key（如
online_recent_3600），用定时任务每分钟BITOP AND合并滚动窗口，但普通在线统计不需要这么复杂
用户 ID 作为 offset 的边界和风险
Bitmap 的 offset 必须是非负整数，且最大支持 2^32 - 1（约 42 亿）。但真实业务中，用户 ID 很可能是字符串、UUID 或带前缀的数字（如 U10086），不能直接当 offset。
- ✅ 安全做法：用自增整型 UID（如数据库主键），或对字符串 ID 做确定性哈希（如
crc32($uid) & 0x7FFFFFFF），再取模到合理范围（比如 % 100000000） - ❌ 危险操作：直接
intval($uid)转换 UUID，结果为 0，所有用户挤在同一个 bit 位 - ⚠️ 注意：offset 过大会导致底层字符串分配过大（
(offset / 8) + 1字节），比如 offset=10 亿 → 占约 125MB 内存，必须提前规划上限
真正容易被忽略的不是命令怎么写，而是 key 的序列化行为和 offset 的合法性校验 —— 这两点一旦出错，统计就全盘失效，且问题隐蔽，日志里还看不出异常。
