当前位置：首页 > 文章列表 > 数据库 > Redis > Redis BF.SCANDUMP和BF.LOADCHUNK怎样配合迁移过滤器

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

来源：17golang原创 2026-10-13 18:55:38 0浏览收藏

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 的内部分块格式恢复过滤器。因此，数据块不能转成普通文本后再拼接。

Redis BF.SCANDUMP与BF.LOADCHUNK在源Redis、二进制传输层和目标Redis之间的结构关系说明图 — 图1：结构说明图，查看 BF.SCANDUMP 产生的迭代器/数据块与 BF.LOADCHUNK 装载目标之间的静态关系。

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

迁移程序需要保存完整的 (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 只适合作为应用层复核动作，不应把某一个元素的查询结果当成整个过滤器的逐字节校验。布隆过滤器本身允许误判“存在”，迁移检查应结合源端和目标端的业务样本、键状态以及传输日志。

Redis Bloom过滤器迁移中的迭代器结束标记、数据块配对和目标键覆盖边界说明图 — 图2：边界说明图，查看迭代器状态、原样数据块和目标键覆盖之间的约束关系。

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

场景	更合适的做法	原因
过滤器较大，不能一次性放进普通转储流程	使用 BF.SCANDUMP + BF.LOADCHUNK	接口按分块返回数据，应用可以分段保存和传输。
数据块需要经过消息队列或文件	使用二进制安全字段	不能依赖默认文本编码，也不能丢掉 iterator。
目标键已经存在	先确认覆盖范围，再执行装载	BF.LOADCHUNK 会覆盖目标 Bloom filter。
源端仍在持续写入	先冻结写入或安排一致的迁移窗口	扫描和装载需要围绕同一份过滤器数据完成。
目标 Redis 没有对应模块命令	先确认 RedisBloom 能力和版本兼容	BF.SCANDUMP 与 BF.LOADCHUNK 不是 Redis 字符串的通用命令。