Redis BF.SCANDUMP和BF.LOADCHUNK怎样配合迁移过滤器

RedisBloom 的 BF.SCANDUMP 和 BF.LOADCHUNK 要成对使用：源 Redis 反复执行 BF.SCANDUMP key iterator，把每次返回的非零迭代器和二进制数据块原样保存；目标 Redis 再把同一组 (iterator, data) 交给 BF.LOADCHUNK，直到扫描端返回迭代器 0。这套方式适合不能放进一次性 DUMP/RESTORE 的大布隆过滤器。

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

最容易出错的地方有三个：第一次扫描必须从 0 开始；非零迭代器必须和对应的数据块一起保存；装载命令会覆盖目标键，迁移期间不能让源过滤器继续变化。下面按这三个边界拆开说明。

两个命令分别负责什么

BF.SCANDUMP 是源端的增量导出接口，首次调用的迭代器是 0，后续把上一次返回的迭代器传回去。它会返回下一次迭代器和当前数据块，直到迭代器再次变成 0，表示扫描完成。

BF.LOADCHUNK 是目标端的恢复接口，参数结构是目标键、扫描返回的迭代器和数据块。它不是把一个普通字符串追加到目标键，而是按照 RedisBloom 的内部分块格式恢复过滤器。因此，数据块不能转成普通文本后再拼接。

用二进制安全的方式连续读取全部分块

迁移程序需要保存完整的 (iterator, data) 对，而不是只保存数据。源端连接也要保持二进制响应：如果客户端启用了 decode_responses=True，数据块可能先被当作文本解码，后续就无法原样交给目标端。

from redis import Redis

def export_filter(source: Redis, key: str) -> list[tuple[int, bytes]]:
    # 从 0 开始，0 只表示扫描起点；后续使用服务端返回的迭代器。
    iterator = 0
    chunks = []

    while True:
        # 返回值是 [下一迭代器, 二进制数据块]，不要把 data 当作普通文本。
        next_iterator, data = source.execute_command("BF.SCANDUMP", key, iterator)
        if next_iterator == 0:
            # 迭代器回到 0 代表扫描结束，这次没有新的分块需要装载。
            break
        chunks.append((next_iterator, data))
        iterator = next_iterator

    return chunks

# decode_responses=False 保留 BF.SCANDUMP 返回的原始字节。
source = Redis(host="source-redis", port=6379, decode_responses=False)
chunks = export_filter(source, "user_email_bf")

如果需要把分块暂存在文件或消息队列中，传输层也必须支持二进制字段。可以给每个分块附带迭代器，但不要修改数据内容，也不要只按数组下标保存而丢掉服务端返回的迭代器。

目标端按配对关系装载过滤器

装载时逐个取出原来的迭代器和数据块，调用 BF.LOADCHUNK。目标键不存在时由装载过程建立；目标键已经存在时，官方文档明确说明该命令会覆盖它，所以正式迁移前应先确认目标键就是允许替换的副本。

def import_filter(target: Redis, key: str, chunks: list[tuple[int, bytes]]) -> None:
    for iterator, data in chunks:
        # iterator 和 data 必须来自同一次 BF.SCANDUMP，保持原配对关系。
        target.execute_command("BF.LOADCHUNK", key, iterator, data)

target = Redis(host="target-redis", port=6379, decode_responses=False)
import_filter(target, "user_email_bf", chunks)

# 迁移程序可在这里发起一次查询，确认目标端已经有该过滤器键。
exists = target.execute_command("BF.EXISTS", "user_email_bf", "demo@example.com")

这里的 BF.EXISTS 只适合作为应用层复核动作，不应把某一个元素的查询结果当成整个过滤器的逐字节校验。布隆过滤器本身允许误判“存在”，迁移检查应结合源端和目标端的业务样本、键状态以及传输日志。

迁移时的选择规则和常见误区

不要把这组命令误解成集群槽位迁移工具，它只处理一个 Bloom filter 键的内部数据；也不要在每次读取分块后重新创建过滤器，否则会破坏服务端返回的迭代器与数据块关系。

常见问题

为什么 BF.SCANDUMP 第一次必须传 0？

0 是官方约定的扫描起点。后续调用应使用上一次返回的非零迭代器；当返回值重新变成 0 时，说明没有更多数据块。

能不能把 data 转成字符串再写入文件？

不建议。应使用二进制方式保存和读取；如果业务协议只能传文本，就要由传输协议明确承担可逆的二进制编码，并在交给 BF.LOADCHUNK 前恢复为原始字节。

目标端需要先执行 BF.RESERVE 吗？

迁移流程的核心是把 BF.SCANDUMP 返回的分块交给 BF.LOADCHUNK，不要先用另一套参数创建一个不同的过滤器。若目标环境或客户端对空键、模块版本有额外限制，应先按目标环境文档确认，再决定是否清理同名键。

小结

记住一条最小规则：BF.SCANDUMP 负责产生完整的 (iterator, data) 分块序列，BF.LOADCHUNK 负责在目标键上按原配对关系恢复；iterator=0 是开始或结束标记，数据块要二进制安全，目标键覆盖要在迁移前明确。