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

Switch between Kafka and Woodpecker

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

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

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

With Helm​

Switch from Kafka to Woodpecker (Helm)​

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

步骤 2：执行 MQ 切换。 暴露 MixCoord 管理接口，然后调用 switch 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：（可选）停止 Kafka 并清理。 对于 builtin Kafka，删除 Kafka pods 及其 PVCs。对于 external Kafka，清理外部 Kafka 实例中的 Milvus topics，它们遵循格式 <cluster_prefix>-dml_<seqNo>_<TimeTick><Version>。

如果你计划之后切回 Kafka，请先清理数据/topics，以避免冲突。

从 Woodpecker 切换到 Kafka (Helm)​

步骤 1：验证 Milvus 实例正在运行。

步骤 2：配置目标 Kafka 连接并重启 Milvus。 执行切换前，Milvus 需要先知道 Kafka 连接配置，因此请通过 extraConfigFiles 将其写入 user.yaml，并使用 helm upgrade 应用配置（这会滚动重启 Pod）。Switch MQ 功能要求设置 streaming.enabled=true。有关 SASL/SSL 的详细信息，请参阅 Connect to Kafka with SASL/SSL。

YAML
# values.yaml
extraConfigFiles:
  user.yaml: |+
    kafka:
      brokerList:
        - <your_kafka_address>:<your_kafka_port>
      saslUsername:
      saslPassword:
      saslMechanisms: PLAIN
      securityProtocol: SASL_SSL
Shell
helm upgrade -i my-release zilliztech/milvus \
  --set kafka.enabled=true \
  --set woodpecker.enabled=false \
  --set streaming.enabled=true \
  -f values.yaml

等待所有 Pod 进入 Ready 状态，然后确认 Kafka 访问配置已渲染到 Milvus 配置中。

步骤 3：执行 MQ 切换。

确保目标 Kafka 中不包含此前配置留下的 Milvus topic。如果这是你第一次切换到 Kafka，可以跳过此说明；否则请先清理同名的残留 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": "kafka"}'

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

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

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

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

With Milvus Operator​

从 Kafka 切换到 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：（可选）停止 Kafka 并清理资源。 对于 builtin Kafka，删除 Kafka pods 及其 PVC。对于 external Kafka，清理 Milvus topics（格式为 <cluster_prefix>-dml_<seqNo>_<TimeTick><Version>）。

从 Woodpecker 切换到 Kafka（Milvus Operator）​

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

Step 2：配置目标 Kafka 连接并重启 Milvus。 将 Kafka 连接配置放在 spec.config 下（Operator 会将 spec.config 渲染到 user.yaml），并设置 MQ 类型；应用 CR 后，Pod 会使用新配置滚动重启。有关 SASL/SSL 的详细信息，请参阅 Connect to Kafka with SASL/SSL。

YAML
# change_configmap.yaml
apiVersion: milvus.io/v1beta1
kind: Milvus
metadata:
  name: my-release
  labels:
    app: milvus
spec:
  config:
    kafka:
      brokerList:
        - <your_kafka_address>:<your_kafka_port>
      saslUsername:
      saslPassword:
      saslMechanisms: PLAIN
      securityProtocol: SASL_SSL
  dependencies:
    msgStreamType: kafka
Shell
kubectl patch -f change_configmap.yaml --patch-file change_configmap.yaml --type merge

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

Step 3：执行 MQ 切换。

确保目标 Kafka 中不包含之前配置留下的 Milvus topic。如果这是你第一次切换到 Kafka，可以跳过此说明；否则请先清理同名的残留 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": "kafka"}'

Step 4：确认切换已完成。

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

切换成功后，日志中会包含 [mqTypeValue=kafka]。

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

支持的场景​

源 MQ目标 MQHelmMilvus Operator
内置 KafkaWoodpecker (MinIO)支持支持
外部 KafkaWoodpecker (MinIO)支持支持
Woodpecker (MinIO)外部 Kafka支持支持
KafkaWoodpecker (local)支持但不推荐 （所有 pod 都需要共享 FS）不支持