Woodpecker 部署与配置

Woodpecker 是 Milvus 3.x 中的 默认 message queue（write-ahead log，WAL）。它是专为对象存储设计的云原生 WAL，具备高吞吐、低运维开销和无缝扩展能力。如需了解架构和基准测试详情，请参见 Woodpecker。

概述

• 在 Milvus 3.x 中，Woodpecker 是 默认 的 WAL/message queue，作为 logging service 提供有序写入和恢复能力。不需要外部 message-queue service（例如 Pulsar 或 Kafka）。
• Woodpecker 可以 嵌入式 运行在 Milvus/Streaming Node 中（默认），也可以作为拥有独立 pod 的 专用服务 运行（仅适用于 distributed/cluster）。
• 它支持三种 storage.type 模式：object storage（minio，默认）、local file system（local）和专用 service。参见 Deployment modes。

快速开始

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

YAML

mq:
  type: woodpecker

注意：为正在运行的集群切换 mq.type 属于升级操作。请严格遵循升级流程，并先在全新集群上验证，再切换生产环境。

配置

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

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 来存储轻量级 metadata。
• prefix：metadata 的 key prefix。默认值：woodpecker。
• woodpecker.client
• 控制客户端侧的 Segment 追加、滚动和审计行为，用于平衡吞吐量和端到端延迟。
• woodpecker.logstore
• 控制日志 Segment 的同步、Flush、Compaction 和读取策略。这些是吞吐量/延迟调优的主要参数。
• woodpecker.storage
• type：minio 用于 MinIO/S3 兼容的对象存储（MinIO/S3/GCS/OSS 等）；local 用于本地/共享文件系统。
• rootPath：存储后端的根路径（对 local 生效；使用 minio 时，路径由 bucket/prefix 决定）。

部署模式

Woodpecker 支持三种 storage.type 模式：

storage.type	Woodpecker 运行方式	WAL backend	Milvus Standalone	Milvus Distributed (cluster)
minio （默认）	嵌入在 Milvus/Streaming Node 中	Object storage（MinIO/S3 兼容）	支持	支持
local	嵌入在 Milvus/Streaming Node 中	本地文件系统	支持	有限制（所有节点都需要共享文件系统，例如 NFS）
service	独立 Woodpecker service （拥有自己的 pods）	Object storage（MinIO/S3 兼容）	不支持	支持

Notes：

• 使用 minio 时，Woodpecker 与 Milvus 共享同一个 object storage（MinIO/S3/GCS/OSS 等）。
• 使用 local 时，单节点本地磁盘仅适用于 Standalone。如果所有 pods 都可以访问共享文件系统（例如 NFS），Cluster 模式也可以使用 local。
• service 模式会将 Woodpecker 作为独立、可单独扩展的 service 运行，并且仅适用于分布式/Cluster 部署。 Standalone 部署使用嵌入式模式（minio 或 local）。

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

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

Provider / service	状态	说明
Azure Blob Storage	支持	使用原生 Azure SDK。
AWS S3	支持	原生 S3，完整支持 Conditional Write。
MinIO (>= 2024-12)	支持	完整支持 S3 Conditional Write。
Aliyun OSS	支持	通过其 S3 兼容接口支持。
Tencent COS	支持	通过其 S3 兼容接口支持。
Google Cloud Storage (GCS)	支持	通过 S3 interoperability mode 支持。
Huawei Cloud OBS	不支持	缺少所需的 Conditional Write 语义。
VAST Data	支持	已由社区验证；仅适用于未启用版本控制的 bucket。
Other S3-compatible storage	部分支持	取决于是否完整支持 S3 Conditional Write 语义。

说明：

• 兼容性取决于原生 SDK 支持，或是否支持 S3 Conditional Write 语义。
• 如果你为 Woodpecker 自托管 MinIO，请使用 RELEASE.2024-12-18T13-15-44Z 或更高版本。
• 此矩阵反映 当前讨论，并可能随着后端支持的进一步验证而变化。

部署指南

使用 Milvus Operator 在 Kubernetes 上为 Milvus 集群启用 Woodpecker（storage=minio）

安装 Milvus Operator 后，可以使用官方示例启动启用了 Woodpecker 的 Milvus 集群：

Shell

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

该示例将 Woodpecker 配置为 message queue，并启用 Streaming Node。首次启动可能需要拉取镜像；请等待所有 pod 就绪：

Shell

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

准备就绪后，你应会看到类似以下的 pod：

Text

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 集群。

Shell

kubectl delete milvus my-release

如需调整 Woodpecker 参数，请参考 Configuration 中的设置。

使用 Helm Chart 在 Kubernetes 上为 Milvus 集群启用 Woodpecker（storage=minio）

首先按照 Run Milvus in Kubernetes with Helm 中的说明添加并更新 Milvus Helm chart。

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

• Cluster 部署（推荐配置，启用 Woodpecker 和 Streaming Node）：

Shell

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

• Standalone 部署（启用 Woodpecker）：

Shell

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

部署完成后，按照文档配置 port-forward 并连接。如需调整 Woodpecker 参数，请参考 Configuration 中的设置。

为 Docker 中的 Milvus Standalone 启用 Woodpecker (storage=local)

在 Milvus 3.x 中，Docker standalone 部署默认使用以 本地文件系统 作为 WAL 后端的 Woodpecker，无需额外配置。请参阅 Run Milvus in Docker：

Shell

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 应用编辑：

YAML

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

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

按照 Run Milvus with Docker Compose 操作。示例：

Shell

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 Cluster 启用 Woodpecker service mode（Helm）

对于 Woodpecker service mode，建议使用即将发布的 Milvus 3.0.1 或后续版本，并搭配 Woodpecker v0.1.36 或后续版本，以获得 compaction cleanup 和 group commit 优化。

Woodpecker service mode 是 Milvus 3.0 的功能。对于 distributed/cluster 部署，你可以将 Woodpecker 作为 dedicated service （独立 pod）运行，而不是将其嵌入 Streaming Node。为此，需要设置 streaming.woodpecker.embedded=false：

Shell

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

这会将 Woodpecker 部署为专用 StatefulSet（my-release-milvus-woodpecker，默认 4 个副本），并由 headless service 暴露。它通过端口 18080 （service）、17946 （gossip）和 9091 （metrics）组成 gossip 集群，并使用 MinIO 作为存储后端。该 service 需要 3 个节点达到 quorum；默认 4 个副本可在容忍单个节点故障的同时保持 quorum，因此不要将 woodpecker.replicaCount 设置为低于 3。随后，集群中会包含一组独立的 woodpecker pod：

Text

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

Woodpecker service mode 仅适用于 distributed/cluster 部署；standalone 部署会以嵌入方式运行 Woodpecker（minio 或 local）。Milvus Operator 目前尚不支持 Woodpecker service mode。

吞吐量调优建议

Woodpecker 在 embedded 模式和 service 模式（Milvus 3.0 功能）下的吞吐量和延迟特征不同。以下建议按模式组织。

Embedded 模式

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

• 存储侧
• 对象存储（minio/S3-compatible）：提高并发度和对象大小（避免产生过小对象）。注意网络和 bucket 带宽限制。单个基于 SSD 的 MinIO 节点在本地通常上限约为 100 MB/s；单个 EC2 到 S3 的吞吐量可达到 GB/s。
• 本地/共享文件系统（local）：优先使用 NVMe/高速磁盘。确保文件系统能够妥善处理小写入和 fsync 延迟。
• Woodpecker 参数
• 增大 logstore.segmentSyncPolicy.maxFlushSize 和 maxFlushThreads，以实现更大的 flush 和更高的并行度。
• 根据存储介质特性调整 maxInterval （通过更长的聚合时间在延迟和吞吐量之间取舍）。
• 对于对象存储，可考虑增大 segmentRollingPolicy.maxSize，以减少 Segment 切换。
• Client/application 侧
• 使用更大的 batch size，并增加并发 writer/client 数量。
• 控制 refresh/index build 的触发时机（先批量累积再触发），避免频繁的小写入。

Service mode（Milvus 3.0+）

Service mode 在保留以对象存储为后端的 WAL 的高写入吞吐能力的同时，也提供低延迟（见 Latency）。上文关于存储端和客户端的调优仍然适用；此外，由于 Woodpecker 作为独立服务运行，你可以通过增加副本（woodpecker.replicaCount，默认值为 4）来水平扩展写入能力。写入还可受益于 one-RTT quorum replication，以及避免 broker forwarding 的 topology-aware reads。

Batch insert demo — 使用以下示例测量写入吞吐量：

Python

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}")

延迟

Embedded 模式

Woodpecker 是一种面向对象存储设计的云原生 WAL，在吞吐量、成本和延迟之间做出权衡。轻量级 Embedded mode 优先优化成本和吞吐量，因为大多数场景只要求数据在一定时间内完成写入，而不是要求单个写请求具备低延迟。因此，Woodpecker 采用批量写入：默认情况下，本地文件系统存储后端的写入间隔为 10ms，类 MinIO 存储后端的写入间隔为 200ms。在写入较慢时，最大延迟等于间隔时间加上 flush 时间。

请注意，批量插入不仅会由时间间隔触发，也会由 batch size 触发；默认 batch size 为 2MB。

Service 模式（Milvus 3.0+）

Service mode 可带来 毫秒级写入延迟，与传统三副本本地磁盘 WAL 处于同一量级，同时保持低成本。在典型的三副本跨 AZ 部署中，写入延迟仍保持在毫秒级。它通过以下方式实现：

• One-RTT quorum writes — 客户端驱动的 replication 可在一次往返内完成 quorum write，跨 AZ 流量固定为两份 Replica 数据量（相比之下，broker/leader-based replication 通常会产生额外约 1/3 的跨 AZ 流量）。
• Topology-aware single-hop reads — 每次读取都会直接访问最近的 Replica，而不是通过 broker 转发，从而避免 broker-based 系统中的随机跨 AZ 读取（约 2/3 的跨 AZ 读取流量）。
• Immediate object-storage upload after Segment rolling — 每个 Segment 都会跟踪其完整生命周期，并在 rolling 后立即上传到对象存储，从而在不牺牲延迟的情况下保持较低的本地磁盘占用和存储成本。
• No continuous node-to-node replication — 日志持久化到作为共享存储的对象存储，因此 failover 只需重新上传幸存的 Replica（无需整节点复制），扩展不受节点间 replication 带宽限制，大规模节点替换也不会引发 replication storm。

在跨 AZ 部署中，与 broker-based log 系统相比，service mode 还可节省约 1/3 的写入 和 2/3 的读取 跨 AZ 网络流量。如需了解完整设计和成本分析，请参阅 Woodpecker Architecture。

如需了解架构、部署模式（MemoryBuffer / QuorumBuffer）和性能详情，请参阅 Woodpecker Architecture。

如需了解更多参数详情，请参阅 Woodpecker GitHub repository。