跳到主要内容
版本：v3.0.x

在 RocksMQ 和 Woodpecker 之间切换

本页介绍如何在 RocksMQ 和 Woodpecker （本地或 MinIO backend）之间双向切换 Milvus Standalone (Docker Compose) 部署的消息队列（MQ）。如需了解通用工作流和前提条件，请参阅 切换消息队列。

  • 前提条件： Switch MQ 功能仅在 Milvus 3.0 及更高版本 中可用。开始前，请先将 Milvus 实例升级到 Milvus 3.0 或更高版本；早期版本不支持该功能。
  • 切换 MQ 需要使用 Docker Compose 部署（该部署支持 etcd 配置源）。单容器 Docker 部署不支持切换。

从 RocksMQ 切换到 Woodpecker​

Step 1: Verify the Milvus instance is running​

确认你的 Milvus Standalone Docker Compose 实例正在正常运行。例如，可以创建一个测试 Collection、插入数据并执行查询。

Step 2: Configure Woodpecker storage​

在不更改 mqType 值的情况下，将 Woodpecker 设置添加到 Milvus 配置中。运行 docker exec -it milvus-standalone bash 进入容器，然后编辑 /milvus/configs/user.yaml：

YAML
woodpecker:
  storage:
    type: minio   # minio or local

重启 Milvus 实例以应用配置：

Shell
docker compose restart

Step 3: Execute the MQ switch​

如果这是你第一次切换到 Woodpecker，请跳过此说明。否则，请在再次切换前清理残留的 Woodpecker meta 和 data，残留数据可能会导致异常行为。

Shell
curl -X POST http://<mixcoord_addr>:<mixcoord_port>/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "woodpecker"}'

MixCoord 端口通常为 9091。

Step 4: 验证切换已完成​

Shell
docker logs milvus-standalone | grep "successfully updated mq.type configuration in etcd"

切换成功时会记录 [mqTypeValue=woodpecker]。

Step 5:（可选）清理 RocksMQ 数据​

RocksMQ 数据位于 docker-compose.yaml 中定义的 volumes/milvus/rdb_data 和 volumes/milvus/rdb_data_meta_kv 目录。如果你计划之后切回 RocksMQ，请先清理这些文件以避免冲突。

从 Woodpecker 切换到 RocksMQ​

Step 1：验证 Milvus 实例正在运行​

确保你的 Milvus Standalone Docker Compose 实例正常运行。

Step 2: Execute the MQ switch​

确保实例中没有上一次运行遗留的 RocksMQ 数据。如果这是你第一次切换到 RocksMQ，可以跳过此提示；否则请先清理相关的 RocksMQ meta 和 data。

Shell
curl -X POST http://<mixcoord_addr>:<mixcoord_port>/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "rocksmq"}'

Step 3: Verify the switch is complete​

Shell
docker logs milvus-standalone | grep "successfully updated mq.type configuration in etcd"

切换成功后，日志中会显示 [mqTypeValue=rocksmq]。

Step 4: (Optional) Clean up Woodpecker data​

  • Metadata (etcd)： Woodpecker key prefix 通常为 woodpecker/...。使用 etcdctl get woodpecker --prefix 查看，然后删除。
  • Storage data： 在 MinIO mode 下，删除 bucket 中 <rootPath>/wp/... （通常为 files/wp/...）下的 log data；在 local mode 下，数据位于本地磁盘的 volumes/milvus/data/wp/...。

如果你计划之后切回 Woodpecker，请先清理这些文件，以避免冲突。

Supported scenarios​

Source MQTarget MQ状态说明
RocksMQWoodpecker (MinIO/local)支持
Woodpecker (MinIO/local)RocksMQ支持
Woodpecker MinIOWoodpecker local不支持在 Woodpecker 存储模式之间切换需要额外处理元数据，目前尚不支持。
Woodpecker localWoodpecker MinIO不支持同上。
RocksMQ / WoodpeckerExternal Pulsar / Kafka支持但不推荐尽量保持 standalone 实例简单。