# 

跨实例迁移一份缓存，脚本按前缀分批扫出来、攒一批写过去。跑完对账：源实例一百二十万键，目标一百一十八万，少了两万。退出码是零，每一批日志都写着成功。

先怀疑目标端写失败被吞，翻了异常日志，干净；再怀疑网络抖动，重跑一遍，少的数量变成一万七。数目会变，说明不是某一批固定丢失，而是读的那一侧本来就没读全。

## 迁移完了数量少两万，是丢数据了吗？

多数情况没丢，是扫的时候提前收工了。这类脚本最常见的写法是把批量扫描当翻页：每轮取一小批，若这一批少于设定批量，就认为到底了。

但这个批量参数只是提示，不是每页多少条。一轮返回九条不代表后面没有了。把它当页码用，脚本会在很多轮里提前退出，而且退得很体面，一条错误都不打。

更麻烦的是它自我掩盖：提前结束意味着后面的键根本没被访问，日志里连读取失败都不会出现，只能靠总数对账发现。

## 官方对 SCAN 的承诺到底是什么？

官方文档把承诺写得非常克制，三条保证加一条代价：

> Starting an iteration with a cursor value of 0, and calling SCAN until the returned cursor is 0 again is called a full iteration.
> A full iteration always retrieves all the elements that were present in the collection from the start to the end of a full iteration.
> A full iteration never returns any element that was NOT present in the collection from the start to the end of a full iteration.
> A given element may be returned multiple times. It is up to the application to handle the case of duplicated elements

第一行定义了什么算完整遍历：从游标零开始，一直调到游标重新变成零。第二三行是一对互补保证，不漏元素，也不凭空给出不存在的元素。第四行是代价：同一元素可能返回多次，去重是应用的事。

这几条保证全都挂在完整遍历这个前提上。循环没走完就退出，保证一条都不成立，这就是那次事故的全部原因。

另外这一页并没有对返回顺序作出承诺，所以校验逻辑里别写按顺序比对，只当它不可依赖就好。

## 为什么 COUNT 只是提示不是页大小？

因为它的原意是每次调用的工作量，不是返回条数：

> While SCAN does not provide guarantees about the number of elements returned at every iteration, it is possible to empirically adjust the behavior of SCAN using the COUNT option. Basically with COUNT the user specifies the amount of work that should be done at every call in order to retrieve elements from the collection. This is just a hint for the implementation
> The default COUNT value is 10.

第一段最后半句是关键：just a hint。实现可以按自己的编码结构决定返回多少条。第二段提醒默认值只有十，不显式设置的话轮数会多到离谱。

| COUNT 取值 | 每轮实际返回 | 典型影响 |
| --- | --- | --- |
| 不设置（默认十） | 十上下浮动 | 轮数多，总耗时偏高 |
| 设成一百 | 受编码结构影响 | 通常接近但不等 |
| 设成一千 | 可能超过一千 | 单轮阻塞时间变长 |

工作量变大意味着单轮更久。迁移期间若还有线上读，主线程被占住的时间就是真实的抖动来源。

## 拿到空批次能不能当成结束？

不能，文档写得很直白：

> SCAN family functions do not guarantee that the number of elements returned per call are in a given range. The commands are also allowed to return zero elements, and the client should not consider the iteration complete as long as the returned cursor is not zero.

意思是允许返回零个，只要游标还不是零就不能认为结束。判断结束的唯一依据是游标回到零，跟这一轮拿回几条无关。

| 本轮游标 | 本轮条数 | 正确解读 |
| --- | --- | --- |
| 非零 | 有数据 | 继续，这是常态 |
| 非零 | 零条 | 继续，可能只是空桶 |
| 零 | 有数据 | 处理完这批再结束 |
| 零 | 零条 | 真正结束 |

第二行是这次翻车的直接原因。空桶在哈希分布不均匀时很常见，一轮扫过几个空桶就返回零条，脚本立刻收工，后面的桶一次都没被看到。

## 小集合为什么一次就全给了？

因为编码方式不同，文档专门说明了这个特例：

> When iterating Sets encoded as intsets ... or Hashes and Sorted Sets encoded as ziplists ... usually all the elements are returned in the first SCAN call regardless of the COUNT value.

被编码成紧凑结构的集合，通常第一次调用就把元素全返回，跟 COUNT 设多少无关。这会造成错觉：键很少时脚本表现完全正常，等数据量上来、编码换成散列表，行为立刻变。

所以用几十个键做迁移测试，是测不出这个 bug 的。

## 重复返回的键该怎么处理？

按幂等写，别假设每个键只来一次。迁移场景里重复返回通常无害，写过去的是同一个值，覆盖一遍还是那个值。

真正出问题的是带计数的操作：自增、追加列表、按条数累加统计，重复就会让结果翻倍。这类键必须先判类型，或者改成幂等覆盖写。

| 写入方式 | 重复返回的后果 | 建议 |
| --- | --- | --- |
| 覆盖写字符串 | 无影响 | 可直接使用 |
| 自增计数 | 数值翻倍 | 改为先读后写 |
| 追加列表 | 元素重复 | 按整表覆盖 |
| 累加统计指标 | 总数偏大 | 本地先聚合去重 |

第四行是复盘才发现的：脚本自己维护的已迁移计数被重复返回放大，恰好掩盖了漏扫造成的偏小，两边一抵消，日志看着还挺正常。

## 迁移后怎么校验数量？

不要只比总数，总数相等也可能一边多一边少凑巧平衡。分三步：按类型计数、按前缀分段计数、随机抽样比对内容。

```python
import redis

def full_scan(conn, pattern="*", count=1000):
    cursor, total, seen = 0, 0, set()
    while True:
        cursor, keys = conn.scan(cursor=cursor, match=pattern, count=count)
        for k in keys:
            if k in seen:        # 完整遍历允许重复，本地去重
                continue
            seen.add(k)
            total += 1
        if cursor == 0:          # 唯一的结束条件
            break
    return total
```

也可以直接用命令行按前缀各数一遍，先看差异落在哪一段：

```bash
# 注意 --scan 内部同样走完整遍历，不要在中途截断管道
for p in user: order: item:; do
  printf "%-8s src=%s dst=%s\n" "$p" \
    "$(redis-cli -h $SRC --scan --pattern "$p*" | wc -l)" \
    "$(redis-cli -h $DST --scan --pattern "$p*" | wc -l)"
done
```

分段之后差异通常会集中到某几个桶，再针对那几个桶做抽样：

```text
分段    源实例     目标实例    差异
user:   412,880    412,880     0
order:  530,412    530,402     10
item:   256,708    236,708     20000
```

这个分布就是最有力的证据：差异全集中在一个前缀，说明不是随机丢包，而是那一段被提前跳过了。

## 边扫边改为什么更危险？

两条保证的措辞都限定在从遍历开始到结束之间。遍历期间元素被删或新增，行为是未定义的。

源端删掉的键可能扫到也可能扫不到，新增的键可能补上也可能漏掉。最后数量对不上，你分不清是扫描的问题还是业务变更的问题。

可行的做法是先冻结写入，或者接受一个明确窗口：全量迁移、按时间窗补增量、最后用短暂的只读窗口收尾。

## 这套迁移脚本后来怎么改的？

三处改动：循环条件只认游标不看条数；每轮空批次单独计数打日志；写入端全改覆盖写，计数不再本地累加。

这套排查最早散在几次复盘里，后来用 AI墨衍 整理成按现象、验证手段、结论排列的表，把数量对不上拆成空批次、提前收工、重复计数三种成因，下次直接对号。

改完重跑差异归零，耗时从四十分钟降到二十一分钟，因为 COUNT 从默认值调到了合理量级，轮数少了一半。

## 常见问题

**问：把 COUNT 设大是不是就一定更快？**

答：不一定。单轮更久、总轮数更少，收益在中间某个区间最大，设过头会拉长阻塞时间。

## 小结

三句话：判断遍历结束只看游标，不看这轮返回多少条；COUNT 是工作量提示不是页大小，默认只有十；完整遍历保证不漏不多，但允许重复，写入端要按幂等设计。


跨实例迁移一份缓存，脚本按前缀分批扫出来、攒一批写过去。跑完对账：源实例一百二十万键，目标一百一十八万，少了两万。退出码是零，每一批日志都写着成功。

云上缓存实例迁移，按批扫描漏掉了两万个键

人工智能

循环结束条件只看游标归零，不可用空批次判断。COUNT仅作工作量提示，非页大小。遍历可能返回重复键，需去重或幂等写。差异集中在特定前缀说明扫描提前中断，校验应分段对比而非只看总数。

数据处理

代码解释

Redis

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

云上缓存实例迁移，按批扫描漏掉了两万个键-腾讯云开发者社区-腾讯云

云上缓存实例迁移，按批扫描漏掉了两万个键

云上缓存实例迁移，按批扫描漏掉了两万个键

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐