Woodpecker

Woodpecker 是 Milvus 3.x 中的默认消息队列（预写日志，WAL）。它是一款专为对象存储设计的云原生 WAL，具有高吞吐量、低运维开销和无缝可扩展性等特点。有关架构和基准测试的详细信息，请参阅Woodpecker。

概述

• 在 Milvus 3.x 中，Woodpecker 是默认的WAL/消息队列，作为日志服务提供有序写入和恢复功能。无需外部消息队列服务（如 Pulsar 或 Kafka）。
• Woodpecker 可以嵌入Milvus/流式处理节点中运行（默认），也可以作为拥有独立 Pod 的专用服务运行（仅限分布式/集群环境）。
• 它支持三种storage.type 模式：对象存储（minio ，默认）、本地文件系统（local ）以及专用service 。请参阅部署模式。

快速入门

要启用 Woodpecker，请将 MQ 类型设置为 Woodpecker：

mq:
  type: woodpecker

注意：对正在运行的集群切换mq.type 属于升级操作。请仔细遵循升级流程，并在切换至生产环境前，先在全新集群上进行验证。

配置

以下是完整的 Woodpecker 配置块（编辑milvus.yaml 或在user.yaml 中进行覆盖）：

# Related configuration of woodpecker, used to manage Milvus logs of recent mutation operations, output streaming log, and provide embedded log sequential read and write.
woodpecker:
  meta:
    type: etcd # The Type of the metadata provider. currently only support etcd.
    prefix: woodpecker # The Prefix of the metadata provider. default is woodpecker.
  client:
    segmentAppend:
      queueSize: 10000 # The size of the queue for pending messages to be sent of each log.
      maxRetries: 3 # Maximum number of retries for segment append operations.
    segmentRollingPolicy:
      maxSize: 256M # Maximum size of a segment.
      maxInterval: 10m # Maximum interval between two segments, default is 10 minutes.
      maxBlocks: 1000 # Maximum number of blocks in a segment
    auditor:
      maxInterval: 10s # Maximum interval between two auditing operations, default is 10 seconds.
  logstore:
    segmentSyncPolicy:
      maxInterval: 200ms # Maximum interval between two sync operations, default is 200 milliseconds.
      maxIntervalForLocalStorage: 10ms # Maximum interval between two sync operations local storage backend, default is 10 milliseconds.
      maxBytes: 256M # Maximum size of write buffer in bytes.
      maxEntries: 10000 # Maximum entries number of write buffer.
      maxFlushRetries: 5 # Maximum number of flush retries.
      retryInterval: 1000ms # Maximum interval between two retries. default is 1000 milliseconds.
      maxFlushSize: 2M # Maximum size of a fragment in bytes to flush.
      maxFlushThreads: 32 # Maximum number of threads to flush data
    segmentCompactionPolicy:
      maxSize: 2M # The maximum size of the merged files.
      maxParallelUploads: 4 # The maximum number of parallel upload threads for compaction.
      maxParallelReads: 8 # The maximum number of parallel read threads for compaction.
    segmentReadPolicy:
      maxBatchSize: 16M # Maximum size of a batch in bytes.
      maxFetchThreads: 32 # Maximum number of threads to fetch data.
  storage:
    type: minio # The Type of the storage provider. Valid values: [minio, local]
    rootPath: /var/lib/milvus/woodpecker # The root path of the storage provider.

关键注意事项：

• woodpecker.meta
  • type：目前仅支持etcd 。请复用与 Milvus 相同的 etcd 来存储轻量级元数据。
  • prefix：元数据的键前缀。默认值：woodpecker 。
• woodpecker.client
  • 控制客户端侧的分段追加/滚动/审计行为，以平衡吞吐量和端到端延迟。
• woodpecker.logstore
  • 控制日志分段的同步/刷新/压缩/读取策略。这些是调整吞吐量和延迟的主要控制参数。
• woodpecker.storage
  • type：minio 用于 MinIO/S3 兼容的对象存储（MinIO/S3/GCS/OSS 等）；local 用于本地/共享文件系统。
  • rootPath：存储后端的根路径（仅对local 有效；对于minio ，路径由存储桶/前缀决定）。

部署模式

Woodpecker 支持三种storage.type 模式：

storage.type	Woodpecker 的运行方式	WAL 后端	Milvus Standalone	Milvus Distributed（集群）
minio （默认）	嵌入 Milvus/流式处理节点中	对象存储（MinIO/S3兼容）	支持	支持
local	嵌入在 Milvus/流式处理节点中	本地文件系统	支持	受限（所有节点都需要一个共享文件系统，例如 NFS）
service	专用的 Woodpecker 服务（拥有独立的 Pod）	对象存储（MinIO/S3兼容）	不支持	支持

注：

• 在minio 模式下，Woodpecker与Milvus共享同一对象存储（MinIO/S3/GCS/OSS等）。
• 在local 下，单节点本地磁盘仅适用于独立模式。如果所有Pod都能访问共享文件系统（例如NFS），集群模式也可使用local 。
• service 该模式将 Woodpecker 作为独立且可独立扩展的服务运行，仅适用于分布式/集群部署。独立部署则使用嵌入式模式（minio 或local ）。

对象存储兼容性storage.type=minio

下表总结了当 Woodpecker 配置为storage.type=minio 时，目前已知的对象存储后端兼容性。此信息基于GitHub 讨论 #150。

提供商/服务	状态	备注
Azure Blob Storage	支持	使用原生 Azure SDK。
AWS S3	已支持	原生 S3，全面支持条件写入。
MinIO (>= 2024-12)	已支持	完全支持 S3 条件写入。
阿里云 OSS	已支持	通过其兼容 S3 的接口予以支持。
腾讯COS	支持	通过其 S3 兼容接口支持。
Google Cloud Storage (GCS)	支持	通过 S3 互操作模式支持。
华为云 OBS	不支持	缺少所需的条件写入语义。
VAST Data	已支持	已由社区验证；仅支持非版本化存储桶。
其他兼容 S3 的存储	部分支持	取决于是否完全支持 S3 条件写入语义。

注：

• 兼容性取决于原生 SDK 的支持情况或对 S3 条件写入语义的支持情况。
• 如果您为 Woodpecker 自托管 MinIO，请使用RELEASE.2024-12-18T13-15-44Z 或更高版本。
• 此对照表反映了当前的讨论情况，随着后端支持的进一步验证，内容可能会发生变化。

部署指南

在 Kubernetes 上的 Milvus 集群中启用 Woodpecker（Milvus Operator，storage=minio）

安装Milvus Operator 后，请使用官方示例启动一个已启用 Woodpecker 的 Milvus 集群：

kubectl apply -f https://raw.githubusercontent.com/zilliztech/milvus-operator/main/config/samples/milvus_cluster_woodpecker.yaml

此示例将 Woodpecker 配置为消息队列，并启用了流式处理节点。首次启动时，拉取镜像可能需要一些时间；请等待直至所有 Pod 准备就绪：

kubectl get pods
kubectl get milvus my-release -o yaml | grep -A2 status

准备就绪后，您应看到类似以下的 Pod：

NAME                                               READY   STATUS    RESTARTS   AGE
my-release-etcd-0                                  1/1     Running   0          17m
my-release-etcd-1                                  1/1     Running   0          17m
my-release-etcd-2                                  1/1     Running   0          17m
my-release-milvus-datanode-7f8f88499d-kc66r        1/1     Running   0          16m
my-release-milvus-mixcoord-7cd7998d-x59kg          1/1     Running   0          16m
my-release-milvus-proxy-5b56cf8446-pbnjm           1/1     Running   0          16m
my-release-milvus-querynode-0-558d9cdd57-sgbfx     1/1     Running   0          16m
my-release-milvus-streamingnode-58fbfdfdd8-vtxfd   1/1     Running   0          16m
my-release-minio-0                                 1/1     Running   0          17m
my-release-minio-1                                 1/1     Running   0          17m
my-release-minio-2                                 1/1     Running   0          17m
my-release-minio-3                                 1/1     Running   0          17m

运行以下命令以卸载 Milvus 集群。

kubectl delete milvus my-release

若需调整 Woodpecker 参数，请按照“配置”部分中的说明进行设置。

在 Kubernetes 上为 Milvus 集群启用 Woodpecker（Helm 图表，storage=minio）

首先，请按照《使用 Helm 在 Kubernetes 上运行 Milvus》中的说明添加并更新 Milvus Helm 图表。

然后使用以下示例之一进行部署：

– 集群部署（推荐设置：启用 Woodpecker 和流式处理节点）：

helm install 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

– 独立部署（已启用 Woodpecker）：

helm install my-release zilliztech/milvus \
  --set image.all.tag=v3.0.0 \
  --set cluster.enabled=false \
  --set pulsarv3.enabled=false \
  --set standalone.messageQueue=woodpecker \
  --set woodpecker.enabled=true \
  --set streaming.enabled=true

部署完成后，请按照文档说明进行端口转发并建立连接。若需调整 Woodpecker 参数，请参考“配置”部分中的设置说明。

在 Docker 中的 Milvus Standalone 部署中启用 Woodpecker（storage=local）

在 Milvus 3.x 中，Docker 独立部署默认使用 Woodpecker并将本地文件系统作为其 WAL 后端——无需额外配置。请按照《在 Docker 中运行 Milvus Standalone》中的说明操作：

mkdir milvus-wp && cd milvus-wp
curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh
bash standalone_embed.sh start

若需调整 Woodpecker 配置，请在首次启动后编辑生成的 `user.yaml ` 文件，并运行 `bash standalone_embed.sh restart ` 以应用更改（执行 `start ` 会重新生成 `user.yaml` 文件，因此请使用 `restart` 应用编辑内容）：

# user.yaml
woodpecker:
  logstore:
    segmentSyncPolicy:
      maxFlushThreads: 16

为使用 Docker Compose 的 Milvus Standalone 启用 Woodpecker（storage=minio）

请参考《使用 Docker Compose 运行 Milvus》。示例：

mkdir milvus-wp-compose && cd milvus-wp-compose
wget https://github.com/milvus-io/milvus/releases/download/v3.0.0/milvus-standalone-docker-compose.yml -O docker-compose.yml
# By default, the Docker Compose standalone uses Woodpecker
sudo docker compose up -d
# If you need to change Woodpecker parameters further, write an override:
docker exec -it milvus-standalone bash -lc 'cat > /milvus/configs/user.yaml <<EOF
mq:
  type: woodpecker
woodpecker:
  logstore:
    segmentSyncPolicy:
      maxFlushThreads: 16
  storage:
    type: minio
EOF'

# Restart the container to apply the changes
docker restart milvus-standalone

为 Milvus 集群（Helm）启用 Woodpecker 服务模式

Woodpecker服务模式是 Milvus 3.0的一项功能。对于分布式/集群部署，您可以通过设置 `streaming.woodpecker.embedded=false`，将 Woodpecker 作为专用服务（独立 Pod）运行，而非嵌入流式处理节点中：

helm install my-release zilliztech/milvus \
  --set image.all.tag=v3.0.0 \
  --set woodpecker.enabled=true \
  --set woodpecker.image.tag=v0.1.37 \
  --set streaming.enabled=true \
  --set streaming.woodpecker.embedded=false

这将把 Woodpecker 作为独立的 StatefulSet（my-release-milvus-woodpecker ，默认 4 个副本）进行部署，由无头服务作为前端，通过端口18080 （服务）、17946 （闲聊）和9091 （指标）进行闲聊集群，并使用 MinIO 作为其存储后端。 该服务需要3个节点的法定人数；默认的4个副本既能保持法定人数，又能容忍单节点故障，因此请勿将woodpecker.replicaCount 设置为小于 3。该集群还包含一个独立的woodpecker Pod 集合：

my-release-milvus-woodpecker-0
my-release-milvus-woodpecker-1
my-release-milvus-woodpecker-2
my-release-milvus-woodpecker-3

吞吐量调优提示

Woodpecker在嵌入式模式和服务模式（Milvus 3.0 的新功能）下的吞吐量和延迟表现各不相同。以下指南按模式分类。

嵌入式模式

基于Woodpecker 中的基准测试和后端限制，请从以下方面优化端到端写入吞吐量：

• 存储端
  • 对象存储（MinIO/S3兼容）：提高并发数并增大对象大小（避免使用微小对象）。注意网络和存储桶的带宽限制。单个基于SSD的MinIO节点本地吞吐量通常上限约为100 MB/s；单个EC2到S3的传输速率可达GB/s。
  • 本地/共享文件系统（本地）：优先使用 NVMe 或高速磁盘。确保文件系统能良好处理小文件写入及 fsync 延迟。
• Woodpecker 配置参数
  • 增加logstore.segmentSyncPolicy.maxFlushSize 和maxFlushThreads 参数，以实现更大的刷新量和更高的并行度。
  • 根据存储介质特性调整maxInterval （通过延长聚合时间，在延迟与吞吐量之间进行权衡）。
  • 对于对象存储，可考虑增加segmentRollingPolicy.maxSize 以减少分段切换。
• 客户端/应用程序端
  • 使用更大的批处理大小和更多的并发写入者/客户端。
  • 控制刷新/索引构建的时机（在触发前进行批量处理），以避免频繁的小写入。

服务模式（Milvus 3.0+）

服务模式在保持基于对象存储的 WAL 高写入吞吐量的同时，还增加了低延迟（参见“延迟”）。 上述存储端和客户端的调优方法仍然适用；此外，由于 Woodpecker 作为独立服务运行，您可以通过增加副本（woodpecker.replicaCount ，默认 4 个）来水平扩展写入容量，且写入操作可受益于单 RTT 定额复制以及避免经纪人转发的拓扑感知读取。

批量插入演示— 使用以下代码测量写入吞吐量：

from pymilvus import MilvusClient
import random
import time

# 1. Set up a Milvus client
client = MilvusClient(
    uri="http://<Proxy Pod IP>:19530",
)

# 2. Create a collection
res = client.create_collection(
    collection_name="test_milvus_wp",
    dimension=512,
    metric_type="IP",
    shards_num=2,
)
print(res)

# 3. Insert randomly generated vectors
colors = ["green", "blue", "yellow", "red", "black", "white", "purple", "pink", "orange", "brown", "grey"]
data = []

batch_size = 1000
batch_count = 2000
for j in range(batch_count):
    start_time = time.time()
    print(f"Inserting {j}th vectors {j * batch_size} startTime{start_time}")
    for i in range(batch_size):
        current_color = random.choice(colors)
        data.append({
            "id": (j*batch_size + i),
            "vector": [ random.uniform(-1, 1) for _ in range(512) ],
            "color": current_color,
            "color_tag": f"{current_color}_{str(random.randint(1000, 9999))}"
        })
    res = client.insert(
        collection_name="test_milvus_wp",
        data=data
    )
    data = []
    print(f"Inserted {j}th vectors endTime:{time.time()} costTime:{time.time() - start_time}")

延迟

嵌入式模式

Woodpecker 是一款专为对象存储设计的云原生 WAL，在吞吐量、成本和延迟之间实现了权衡。轻量级的嵌入式模式优先考虑成本和吞吐量的优化，因为大多数场景仅要求数据在一定时间内写入，而非对单个写入请求要求低延迟。 因此，Woodpecker 采用批量写入机制，其中本地文件系统存储后端的默认间隔为 10 毫秒，而 MinIO 类存储后端的默认间隔为 200 毫秒。在写入速度较慢的情况下，最大延迟等于间隔时间加上刷新时间之和。

请注意，批量插入不仅由时间间隔触发，还受批量大小影响，其默认值为 2MB。

服务模式（Milvus 3.0+）

服务模式在保持低成本的同时，实现了毫秒级写入延迟——与传统的三副本本地磁盘 WAL 处于同一量级。在典型的三副本跨可用区部署中，写入延迟始终保持在毫秒范围内。其实现方式如下：

• 单 RTT 法定多数写入——客户端驱动的复制可在单次往返内完成法定多数写入，跨可用区流量固定为两个副本的数据量（相比之下，基于代理/领导者的复制通常会产生额外约 1/3 的跨可用区流量）。
• 拓扑感知单跳读取——每次读取都直接发送到最近的副本，而不是通过代理转发，从而避免了基于代理系统中随机的跨可用区读取（约占跨可用区读取流量的 2/3）。
• 分段滚动后立即上传至对象存储——每个分段都会追踪其完整生命周期，并在滚动后立即上传至对象存储，从而在不牺牲延迟性能的前提下，保持本地磁盘占用空间和存储成本处于较低水平。
• 无需持续的节点间复制——日志持久化到充当共享存储的对象存储中，因此故障转移时仅需重新上传幸存的副本（无需复制整个节点），扩展不再受限于节点间复制带宽，且大规模节点替换不会引发复制风暴。

在跨可用区（AZ）部署中，与基于代理的日志系统相比，服务模式还可节省约1/3 的跨可用区写入网络流量和2/3 的跨可用区读取网络流量。有关完整的设计和成本分析，请参阅《Woodpecker 架构》。

有关架构、部署模式（MemoryBuffer / QuorumBuffer）和性能的详细信息，请参阅《Woodpecker 架构》。

有关更多参数详情，请参阅 WoodpeckerGitHub 代码库。