版本：v3.0.x

Switch between Pulsar and Woodpecker

本页介绍如何在 Milvus cluster 中双向切换消息队列（MQ）：在 Pulsar （内置或外部）与 Woodpecker （MinIO 后端）之间切换。关于通用流程和前提条件，请参见 Switch Message Queue。

前提条件： Switch MQ 功能仅在 Milvus 3.0 及之后版本 可用。开始前，请将你的 Milvus 实例升级到 Milvus 3.0 或更高版本，此功能在早期版本中不可用。

切换消息队列是一项 高风险操作。请选择与你的部署方式匹配的章节（With Helm 或 With Milvus Operator），并从头到尾按步骤执行。不要混用 Helm 和 Operator 命令。

With Helm

从 Pulsar 切换到 Woodpecker（Helm）

步骤 1：验证 Milvus 实例正在运行。确保你的 Milvus 集群正常运行，例如创建一个测试 Collection、插入数据并执行查询。

步骤 2：执行 MQ 切换。暴露 MixCoord 管理接口，然后调用切换 API：

Shell
kubectl port-forward --address 0.0.0.0 service/my-release-milvus-mixcoord 29091:9091

在另一个终端中执行：

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

步骤 3：验证切换已完成。

Shell
kubectl logs <mixcoord-pod> | grep "successfully updated mq.type configuration in etcd"

切换成功后，日志中会出现 [mqTypeValue=woodpecker]。

步骤 4：（可选）停止 Pulsar 并清理资源。对于 builtin Pulsar，禁用 Pulsar 并启用 Woodpecker，然后删除 Pulsar PVC：

Shell
helm upgrade my-release zilliztech/milvus \
  --set image.all.tag=v3.0.0 \
  --set pulsarv3.enabled=false \
  --set woodpecker.enabled=true \
  --set streaming.enabled=true \
  --set indexNode.enabled=false

Shell
kubectl get pvc | grep my-release-pulsarv3
kubectl delete pvc <pulsar-pvc-name> ...

对于 external Pulsar，请清理外部 Pulsar 实例中的 Milvus topic。Milvus topic 遵循 <cluster_prefix>-dml_<seqNo>_<TimeTick><Version> 格式，例如 by-dev-rootcoord-dml_10_464633776992639586v0。

如果你计划之后切回 Pulsar，请先清理数据或 topic，以避免冲突。受 Helm chart 限制，目前无法切回 builtin Pulsar 实例。

Switch from Woodpecker to Pulsar (Helm)

Step 1: 确认 Milvus 实例正在运行。

Step 2: 配置目标 Pulsar 连接并重启 Milvus。切换前，Milvus 需要已知 Pulsar 连接信息，因此请通过 extraConfigFiles 将其写入 user.yaml，并使用 helm upgrade 应用配置（这会滚动重启 Pod）。Switch MQ 功能要求 streaming.enabled=true。

YAML
# values.yaml
extraConfigFiles:
  user.yaml: |+
    pulsar:
      address: <pulsar addr>
      port: <pulsar port, e.g. 6650>

Shell
helm upgrade -i my-release zilliztech/milvus \
  --set pulsarv3.enabled=true \
  --set woodpecker.enabled=false \
  --set streaming.enabled=true \
  -f values.yaml

等待所有 Pod 就绪，然后确认 Pulsar 访问配置已渲染到 Milvus 配置中。

Step 3: 执行 MQ 切换。

确保目标 Pulsar 中不包含来自先前配置的 Milvus topic。如果这是你首次切换到 Pulsar，可以跳过此说明；否则，请先清理同名的残留 Milvus topic。

Shell
kubectl port-forward --address 0.0.0.0 service/my-release-milvus-mixcoord 29091:9091

在另一个终端中执行：

Shell
curl -X POST http://127.0.0.1:29091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "pulsar"}'

Step 4: 验证切换已完成。

Shell
kubectl logs <mixcoord-pod> | grep "successfully updated mq.type configuration in etcd"

切换成功时，日志中会出现 [mqTypeValue=pulsar]。

Step 5: （可选）清理 Woodpecker 数据。删除 MinIO/S3 上的 Woodpecker 数据（位于 <rootPath>/wp/... 下，通常为 files/wp/...）以及 etcd 中的 Woodpecker metadata（etcdctl get woodpecker --prefix）。如果你计划稍后切回 Woodpecker，请先清理这些文件。

使用 Milvus Operator

从 Pulsar 切换到 Woodpecker（Milvus Operator）

步骤 1：确认 Milvus 实例正在运行。

步骤 2：执行 MQ 切换。 MixCoord 服务未对外暴露，因此需要在 MixCoord pod 内部调用切换 API：

Shell
kubectl exec -it <mixcoord-pod> -- \
  curl -X POST http://localhost:9091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "woodpecker"}'

步骤 3：确认切换已完成。

Shell
kubectl logs <mixcoord-pod> | grep "successfully updated mq.type configuration in etcd"

切换成功后，日志中会出现 [mqTypeValue=woodpecker]。

步骤 4：在 Operator 中更新 MQ 类型。更新由 Operator 管理的配置，避免 Operator 回滚本次切换。创建 change_configmap.yaml：

YAML
apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
  name: my-release
  labels:
    app: milvus
spec:
  dependencies:
    msgStreamType: woodpecker

Shell
kubectl patch -f change_configmap.yaml --patch-file change_configmap.yaml --type merge

步骤 5：（可选）停止 Pulsar 并清理。对于 builtin Pulsar，卸载 Pulsar release 并删除其 PVC：

Shell
helm uninstall my-release-pulsar
kubectl get pvc | grep my-release-pulsar
kubectl delete pvc <pulsar-pvc-name> ...

对于 external Pulsar，清理 Milvus topics（格式为 <cluster_prefix>-dml_<seqNo>_<TimeTick><Version>）。

如果你计划之后切回 Pulsar，请先清理数据/topics，以避免冲突。由于 Helm chart 的限制，目前无法切回 builtin Pulsar 实例。

Switch from Woodpecker to Pulsar (Milvus Operator)

步骤 1：确认 Milvus 实例正在运行。

步骤 2：配置目标 Pulsar 连接并重启 Milvus。将 Pulsar 连接配置放在 spec.config 下（Operator 会将 spec.config 渲染到 user.yaml），并设置 MQ 类型；应用 CR 后，Pod 会使用新配置滚动重启。

YAML
# change_configmap.yaml
apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
  name: my-release
  labels:
    app: milvus
spec:
  config:
    pulsar:
      address: <pulsar addr>
      port: <pulsar port, e.g. 6650>
  dependencies:
    msgStreamType: pulsar

Shell
kubectl patch -f change_configmap.yaml --patch-file change_configmap.yaml --type merge

等待所有 Pod 就绪，然后确认 Pulsar 访问配置已渲染到 Milvus 配置中。

步骤 3：执行 MQ 切换。

确保目标 Pulsar 中不包含此前配置遗留的 Milvus topic。如果这是你第一次切换到 Pulsar，可以跳过此说明；否则请先清理同名的残留 Milvus topic。

Shell
kubectl exec -it <mixcoord-pod> -- \
  curl -X POST http://localhost:9091/management/wal/alter \
  -H "Content-Type: application/json" \
  -d '{"target_wal_name": "pulsar"}'

步骤 4：确认切换已完成。

Shell
kubectl logs <mixcoord-pod> | grep "successfully updated mq.type configuration in etcd"

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

步骤 5：（可选）清理 Woodpecker 数据。删除 MinIO/S3 上的 Woodpecker 数据（位于 <rootPath>/wp/... 下，通常为 files/wp/...）以及 etcd 中的 Woodpecker metadata（etcdctl get woodpecker --prefix）。如果你计划之后切回 Woodpecker，请先清理这些文件。

Supported scenarios

Source MQ	Target MQ	Helm	Milvus Operator
内置 Pulsar	Woodpecker (MinIO)	支持	支持
外部 Pulsar	Woodpecker (MinIO)	支持	支持
Woodpecker (MinIO)	外部 Pulsar	支持	支持
Pulsar	Woodpecker (local)	支持但不推荐（所有 pod 都需要共享文件系统）	不支持

With Helm​

从 Pulsar 切换到 Woodpecker（Helm）​

Switch from Woodpecker to Pulsar (Helm)​

使用 Milvus Operator​

从 Pulsar 切换到 Woodpecker（Milvus Operator）​

Switch from Woodpecker to Pulsar (Milvus Operator)​

Supported scenarios​