向量数据库集群之痛:2025-2026 真实故障报告与 xerj 的嵌入式 Raft 应对方案

原创2026-10-17 22:20:051,882 阅读
文章标签:搜索引擎全文检索向量数据库数据库后端MCP 服务Agent 记忆人工智能日志分析dsh-plugin

向量数据库集群之痛:2025-2026 真实故障报告与 xerj 的嵌入式 Raft 应对方案

导读:本文以仓库 user-feedback/15-clustering-durability-expectations-2025-2026/02-vector-db-clustering-issues.md 为骨架,系统梳理 2025-2026 年 Qdrant、Milvus、Weaviate、Pinecone 等主流向量数据库在集群一致性、数据持久化与运维复杂度上的真实故障;随后对照 xerj 开源项目(XERJ)在 engine/crates/xerj-cluster 中从零实现的嵌入式 Raft 集群方案,逐层拆解其共识、持久化日志、WAL 复制与自动分区的实现原理与测试证据。读完本文,你将理解"为什么向量数据库集群总出问题",并掌握 xerj 目前集群模式的真实能力边界、三节点部署配置与源码级验证方法。


一、2025-2026 向量数据库集群故障全景

1.1 Qdrant:WAL 损坏、分片迁移竞态与 3 节点下限

根据仓库整理的报告(数据来源:GitHub Issues、Release Notes、官方文档),Qdrant 在 2025-2026 年间暴露出一批数据完整性类缺陷:

编号 问题 状态
#7558 分片迁移过程中的数据竞争(data race in shard transfers) 1.13 修复
#7587 刷盘边界场景导致 WAL 损坏(broken flush edge case) 已修复
#7564 旧集群启用用户自定义分片后启动 panic 已修复
#7400 段部分刷盘时加载损坏段(corrupt segments on load) 已修复
#7375 使用已占用 URI 加入集群会破坏整个集群 已修复
#8584 WAL delta 传输手动恢复不稳定 2026-04 仍开放
#8357 分片快照临时文件在持久化失败时泄漏资源 仍开放
#8349 快照共识冻结测试失败 仍开放

更值得关注的是其集群可用性的结构性限制。Qdrant 官方文档承认:

"当集群中有一个节点宕机时,集群无法对集合执行操作。操作要求超过 50% 的节点在运行,因此这仅在 3 节点及以上的集群中才可能实现。"

"如果两个节点之一的数据被永久丢失或损坏,除快照外无法恢复。只有 3 节点以上的集群才能从单节点永久丢失中恢复。"

也就是说,2 节点集群在 Qdrant 中既不能承受单节点故障,也不能从永久性损坏中恢复——3 节点是最低可用配置。第三方对比(Cipher Projects, 2025)也评价:"Qdrant 虽然支持分布式部署,但横向扩展能力相比更成熟的系统仍在演进,围绕大规模集群的运维工具相对有限。"

仓库中更细粒度的数据点(04-vector-db-qdrant/data-points.md)补充了 75 条实证:例如 #6960 中三节点 commit index 发散到 16,211,980 / 16,211,996 / 3,714,165,集群完全不可用且持续数天;#4626/#4627 中节点重启期间写入丢失导致重启节点与其余节点数据不一致(1,860 vs 1,857 条记录);#5642 显示高吞吐写入(>12,000 points/sec)时共识操作进入连续失败状态;#6431 中 K8s 节点重启后 2/10 pod 永久进入 not-ready。值得注意的是 Qdrant 维护者对 #4626 的回应:

"要实现写入一致性需要两阶段提交或串行写入,两种方案都会损害性能,因此我们决定不做。"

这意味着为了性能主动放弃了写一致性——节点重启窗口内的数据不一致是其明确接受的设计取舍。

1.2 Milvus:4 个外部依赖与运维复杂度

Milvus 的问题集中在架构复杂度上。技术对比普遍认为:"Milvus 的云原生架构设计对大规模系统很强大,但它比简单部署引入更多运维复杂度。""Milvus 将大量摄取工作拆分到与查询流量分离的独立节点类型上。"

仓库文档明确列出了其外部依赖链:

  • etcd:元数据存储
  • MinIO/S3:对象存储(段文件)
  • Pulsar/Kafka:日志流
  • 结论:在存入第一条向量之前,需要先部署 4 个外部系统

用户侧的真实痛点(ML Journey, 2025):"真实用户反馈选择 Milvus 做小原型后,被运维开销困扰。建议:原型阶段先用 Pinecone 或托管 Weaviate,只有规模证明必要后再迁移到自托管。"

1.3 Weaviate 与 Pinecone

Weaviate 的问题主要是扩展与性能:

  • "Weaviate 的集群模式支持更大部署,但扩展不如 Milvus 无缝"(Tensor Blue 对比, 2025);
  • "Weaviate 延迟范围略高,约 50-70ms(对比 Pinecone 40-50ms)"(2026 生产基准)。

Pinecone 的问题则相反——托管服务带来的锁定:

  • "Pinecone 自动扩展资源但限制配置控制——你无法调整索引算法或存储层"(Firecrawl 对比, 2026);
  • "Pinecone 是全托管……费用随搜索量增长成正比上升"(多来源)。

1.4 共同规律:所有集群方案都有问题

仓库文档以一张总表收束:

数据库 核心集群问题
Elasticsearch 脑裂、主节点瓶颈、分片爆炸
Qdrant WAL 损坏、分片迁移竞态、3+ 节点下限
Milvus 4 个外部依赖、运维复杂度
Weaviate 扩展不无缝、延迟更高
Pinecone 厂商锁定、无法自托管、架构不透明

如果继续阅读仓库中更完整的 97 条 GitHub issue 汇编(04-vector-db-qdrant/github-issues-all-vdbs.md),还可以提炼出七条跨数据库共性模式:

  1. WAL/预写日志故障是普遍的:Qdrant (#5503, #7411)、Milvus (#40264, #43185)、Weaviate (#7162, #4038)、Chroma (#4218) 都出现 WAL 相关数据丢失;
  2. 节点重启后共识(Raft)不稳定:Qdrant (#6431, #6348, #5824) 与 Weaviate (#8423, #6284, #5491) 在 K8s pod 重启、节点故障或版本升级后 Raft 共识破裂,需要人工干预;
  3. 误配置导致静默数据丢失:Chroma (#6654, #4330)、Weaviate (#7516, #7162) 的默认配置让用户误以为持久化已开启;
  4. 分布式部署中的 OOM 级联:Milvus (#45602, #40932, #41333, #42712) 的流式/数据/查询节点 OOM 后无法优雅恢复;
  5. etcd 是 Milvus 的单点故障:6+ 个 issue(#43582, #39417, #41106 等)表明 etcd 故障会让整个集群不可达;
  6. 分片/副本管理需要人工干预:Qdrant (#6027, #5549, #6773, #5215) 的重平衡、副本因子调整、磁盘满恢复都没有自动化补救;
  7. 复制正确性缺陷:Weaviate (#6900, #8797, #7087, #6387) 存在竞态、序列化失败与迁移破坏性 bug。

这些模式共同指向一个结论:把共识、复制与段存储绑死在固定节点上的传统集群架构,正是上述故障的温床。这也是下一节 xerj 方案的对照基准。


二、xerj 的回应:嵌入式 Raft,不依赖外部服务

仓库中与上述报告直接对应的设计,是 engine/crates/xerj-cluster 这个 crate。它的定位在 lib.rs 的文档注释中写得很清楚:

"本 crate 从零实现 Raft——不使用任何外部 Raft 库。目标:无重依赖(无 etcd、无 ZooKeeper、无 Consul);适合直接嵌入 xerj server 进程;只承载集群级元数据(索引 schema、分片分配、节点名册);保证完整正确性:领导者选举、日志复制、日志安全、提交规则。"

对照上一节的故障表,这套设计在架构层面直接回答了三个痛点:

  • 消除外部依赖:Milvus 需要 etcd + Pulsar/Kafka + MinIO 四个外部系统,xerj 的共识直接内嵌进单一二进制,不引入任何外部依赖;
  • 用标准 Raft 取代自定义协议:Elasticsearch 的自定义投票协议(ZenWithTerms)被诟病为"复杂、脑裂风险高",而 Raft 是 2014 年论文中已被验证、有严格安全性证明的算法;
  • 元数据规模极小:集群级元数据(索引 schema、分片分配、节点名册)通常只有几 MB,Raft 日志专门复制这些少量状态,而不是复制全部文档数据。

2.1 从零实现的 Raft 核心

raft.rs 实现了 Ongaro & Ousterhout《In Search of an Understandable Consensus Algorithm》(2014) 的标准协议,并显式声明了五条安全性属性:

  • Election Safety:每个任期至多一个领导者
  • Leader Append-Only:领导者从不覆盖或删除自己日志中的条目
  • Log Matching:两份日志若在相同索引与任期包含相同条目,则该索引之前的所有条目完全一致
  • Leader Completeness:某条目在给定任期被提交,则所有更高任期的领导者日志中都存在该条目
  • State Machine Safety:服务器在某索引应用了某条目后,其他服务器永远不会在同一索引应用不同条目

状态机由 RaftState(Follower / Candidate / Leader)与 RaftMessage(AppendEntries / RequestVote 及各自响应)驱动。值得注意的两个实现细节:

选举超时随机化:random_election_timeout() 在 150–300ms 间随机取值(raft.rs),这是 Raft 论文防止"活锁式"反复平票的标准手段。

自身 ID 排除(issue #1168 修复):RaftNode::new 会过滤掉与自身 ID 相同的 peers 条目——文档约定的配置惯例是每个节点都写全量成员表,若不排除自身,三节点环会把集群大小算成 4、多数派算成 3(即全体一致、零容错),且节点会向自己发 RequestVote 并把自身投票计两次。该修复有对应单元测试 test_self_is_excluded_from_peers 验证 majority() == 2。

2.2 持久化 Raft 日志:不复盘就会丢确认写入

xerj 的集群设计没有止步于内存状态机。raft_log.rs 明确指出了内存日志的问题:

"Raft 状态机把日志放在 RAM 的 Vec<LogEntry> 中,重启即丢失。这让整个集群设计不安全——如果领导者在 follower 收到提交之前崩溃,已确认的写入会消失。"

FileRaftLog 因此把条目以追加写(append-only)方式落到 {data_dir}/raft/ 目录,文件格式与索引 WAL 共用同一套帧格式,并带独立魔数 0x5A52_4C32("ZRL2")防止与索引 WAL 混淆:

u32  magic = 0x5A_52_4C_32  ("ZRL2")
u64  entry length
u64  term
u64  index
u8   payload kind
u64  payload length
bytes payload
u32  crc32 of the preceding header + payload

写入流程严格遵守"先持久化、后进内存"的顺序——raft.rs 的 propose 在把条目推入内存日志前先 append 到文件并 fsync,保证调用方拿到 Ok(index) 时写入已经是持久的,即使进程随后崩溃也不丢。重启时通过 with_storage 重放磁盘日志,重建 current_term、voted_for、commit_index。

fsync 采用批量策略:默认每 100ms 或累积 256 条条目触发一次,两个阈值均可通过 [cluster] raft_fsync_ms / raft_fsync_batch 配置。测试 raft_log_persist_test 验证了写入 1000 条后关闭、重新打开仍能恢复全部条目。

2.3 WAL 复制:三种复制模式

replication.rs 实现文档写入的副本传播。基本流程是:文档在主分片节点写入 WAL 后,在向客户端确认之前把 WAL 条目复制到副本节点。支持三种模式:

模式 语义 取舍
Async 主节点写入即确认(fire-and-forget) 最快,主节点崩溃有丢数据风险
Sync { min_replicas } 等主节点 + 至少 N 个副本确认 可控的持久性保证
Quorum 等主节点 + 副本严格多数确认 多数派确认,故障容错更强

WalReplicator 通过 ShardRouter::get_replicas 获取每个分片的副本节点列表(自动排除主节点),逐副本并发发送。复制帧目前通过既有 ClusterTransport 捎带发送(用 term = u64::MAX 哨兵值区分于共识流量,见 make_replication_raft_message)。

2.4 区域(Region)自动拆分与再平衡

与报告中的"分片管理需要人工干预"(Qdrant #6027、#5549 等)形成对照的是,xerj 在 regions.rs 中设计了自动分区:一个 region 是索引内文档键的连续范围 [start_key, end_key),由 RegionManager 负责生命周期:

  • 拆分:region 超过阈值即自动拆分,默认按 size_bytes > 256 MiB 或 doc_count > 1,000,000 触发,取键范围的中点(midpoint_key)一分为二,统计量近似对半;
  • 合并:相邻且都低于 64 MiB 阈值的两个 region 自动合并,副本列表取并集;
  • 初始分配:新索引的 region 按轮询(round-robin)分布到各节点,leader 之外的所有节点自动成为副本;
  • 再平衡:plan_rebalance 根据节点负载(如字节数)规划迁移,从最忙节点向最闲节点逐区迁移,直到负载差进入均值 ±10% 以内。

这些操作全部有单元测试覆盖(test_region_split、test_region_merge、test_rebalance_plan 等),测试分布、邻接性与再平衡方向等不变量。


三、如何实际部署一个 xerj 三节点集群

3.1 配置解读

xerj 的集群模式是配置开关而非独立进程——"一个二进制还是那一个二进制"。默认配置 enabled = false(见 xerj.default.toml),完整的 [cluster] 参数如下:

[cluster]
enabled     = true
port        = 9300                              # 集群内 Raft + 搜索端口
auth_secret = "<同一个 secret,16+ 字符,所有节点相同>"  # 或环境变量 XERJ_CLUSTER_AUTH_SECRET
peers       = [
  "10.0.0.11:9300=10.0.0.11:9300",   # 本节点
  "10.0.0.12:9300=10.0.0.12:9300",
  "10.0.0.13:9300=10.0.0.13:9300",
]
tick_ms = 50

关键参数说明:

  • peers 条目的格式是 "<label>=<address>":节点 ID 就是 socket 地址。如果 label 与自身 bind_address:port 不一致,节点拒绝启动(issue #1171——曾经一个"友好标签"导致该节点的投票响应无法送达)。当前节点是地址与自身 bind_address 和 cluster.port 匹配的那一条;
  • auth_secret 或 XERJ_CLUSTER_AUTH_SECRET 必须设置:没有 secret 节点拒绝启动。生成方式建议 openssl rand -hex 32,最小值 16 字符;
  • TLS 要求:非 loopback 的 bind_address 需要 [tls] 开启(或显式设置 server.allow_insecure_network_bind = true);TLS 开启时,gRPC 明文 h2c 监听需要 tls.allow_insecure_grpc_h2c = true;
  • tick_ms:Raft 状态机驱动周期,生产环境约 50ms。

3.2 启动与观察

在三台机器上分别用各自配置启动:

$ xerj --config /etc/xerj/node-a.toml     # 10.0.0.11
$ xerj --config /etc/xerj/node-b.toml     # 10.0.0.12
$ xerj --config /etc/xerj/node-c.toml     # 10.0.0.13

一秒钟内环会选出领导者。当前最可靠的观察位置是日志(健康检查端点目前只报告应答节点自身,环的成员关系属于 roadmap 中的 wiring 工作):

$ journalctl -u xerj -f | grep xerj_cluster
INFO xerj_cluster::transport: TCP transport listening (authenticated) node=10.0.0.11:9300
INFO xerj_cluster::raft: Starting election node=10.0.0.12:9300 term=1
INFO xerj_cluster::raft: Became leader node=10.0.0.12:9300 term=1

3.3 集群模式现在能做什么、不能做什么

仓库文档对当前能力边界非常坦诚(landing/docs/clustering.html):

现在就能用的:

  • 领导者选举:每个任期恰好一个领导者,150–300ms 随机选举超时,自动故障转移。在 3 节点 loopback 环上实测(tick 50ms):杀掉领导者后约 250ms 选出新领导者,随后数分钟选举稳定。领导者死亡曾导致持续选举抖动,由 issue #1168 修复;
  • 认证传输:每条节点间连接都用集群 secret 做 HMAC-SHA256 质询握手(详见下文 3.4);
  • 死节点隔离:挂死或失联的 peer 只在状态迁移时产生一条 WARN,之后重试退避 100ms → 6.4s,绝不阻塞发往活节点的消息;
  • 持久化本地 Raft 日志:每个节点持久化任期、投票与已提交条目,重启时重放。

现在还不能用的(请务必不要误以为集群已提供数据冗余):

  • 无元数据复制:A 节点创建的索引在 B 节点不存在——目前没有生产路径会提议 ClusterCommand;
  • 无文档复制:在 A 节点 PUT 文档、从 B 节点 GET,返回 404 index_not_found(已在 3 节点环上实测验证);
  • 无分片路由:没有转发到主分片、没有副本读取,每个节点的 API 只服务自身存储;
  • 无节点生命周期 API:没有 drain / activate / remove 端点,没有 region 拆分合并上线。

因此在复制链路落地之前,应把集群节点的数据持久性视为与单节点完全等同。如果今天就需要第二份实时数据副本,官方建议使用 WAL tap(把索引写入实时单向推送到另一个 xerj 或任意 ES 兼容目标)或逐节点备份。仓库公开跟踪复制接线工作(issue #1170)。

3.4 认证传输原理:防重放不是加密

transport.rs 与 auth.rs 定义了认证协议:连接建立时接收方先发送 32 字节每连接随机质询(challenge),发送方用集群 secret 对该质询连同协议上下文串、线缆版本、节点 ID、帧序号与载荷计算 HMAC-SHA256 标签。核心安全属性:

  • 防重放:质询是接收方为每条新连接生成的 32 字节新鲜随机数,被抓包录制的帧重放给同一节点(或反射给另一节点)时,会因质询不符而被拒绝;
  • 防重排/防丢弃/防重复:隐式的帧序号(seq,永不上线)把每帧钉在连接中的位置,重排、丢弃或复制都会导致标签校验失败;
  • 没有未认证模式:节点无 secret 拒绝启动。

但文档也明确了两点边界:HMAC 认证不提供机密性——帧仍是明文 JSON,集群端口应放在可信网络段;不提供节点身份——secret 是集群共享的,只能证明"peer 知道集群 secret",不能证明"peer 是节点 X",成员冒充防护需要 mTLS 或逐节点密钥(更大的设计变更)。

3.5 故障模式:已实测的行为

故障 实测/设计行为
领导者崩溃 follower 超时后选举新领导者——3 节点 loopback 环实测约 250ms(含一次平票重试)。环在死成员缺席时保持稳定,其 Raft 日志留在磁盘供重加入
挂死/失联 peer 状态迁移一条 WARN 后保持安静:重试退避 100ms → 6.4s;发往活节点的消息从不被死节点拖慢;peer 恢复应答时以 INFO 记录 "peer reachable again"
少数派分区 少数派无法达成 quorum,选举永不结束;多数派保住领导者。Raft 安全性成立——每个任期至多一个领导者
节点重加入 相同配置重启后重放本地 Raft 日志、重新参与选举;从领导者日志追赶(快照安装)属于接线 roadmap

四、共识如何与检索协同:分片路由与分布式搜索

xerj 集群的检索路径同样有明确设计。router.rs 实现Jump Consistent Hash(Lamping & Veach, Google 2014):

doc_id ──xxh3──► u64 key ──jump_hash──► shard_id ──routing_table──► node_id

关键性质(均有单元测试验证):同一 (key, num_buckets) 永远映射到同一桶(test_jump_hash_stability);桶数增加时只迁移约 1/N 的键(test_jump_hash_minimal_rebalancing);键分布近似均匀(test_jump_hash_distribution)。ShardRouter::update_from_metadata 可从权威的 ClusterMetadata 刷新路由表,并自动把 num_shards 拓宽到所见的最大分片号。

search.rs 与 coordinator.rs 定义了网关-数据节点两级的消息协议:网关把 SearchRequest 并行扇出(fan-out)到持有相关分片的每个节点,各节点返回局部命中 SearchResponse,网关用 merge_search_responses 合并、重排后返回客户端;写路径则反向——网关把 IndexRequest 转发到目标分片的主节点。本地节点搜索跳过网络,通过 LocalSearcher 直接回调本地引擎。

明确说明:路由、复制与搜索协调的代码与测试真实存在(见 router.rs 与 search.rs 的测试模块),但按照 landing/docs/clustering.html 的现状声明,这些尚未接入生产写入路径——它们更多属于设计先行、随复制接线逐步上线的部分。上文 3.3 节的"现在还不能用"清单,是判断当前能力边界的权威依据。


五、结论:从故障报告到架构对照

把 2025-2026 的故障报告与 xerj 的集群设计放在一起,可以提炼出三条清晰的对照:

  1. 外部依赖是最常见的故障放大器:Milvus 的 etcd 单点故障(6+ issue)、Pulsar 通道分配不均、Chroma 的持久化误配置,本质都是"多个外部系统各自有自己的故障面"。xerj 把共识内嵌进单一二进制,从架构上消掉了这一类故障面;
  2. 共识与复制不能停留在内存:Qdrant 的 WAL 损坏、Weaviate 的重启丢数据、Chroma 的进程退出丢数据,都指向持久化缺失或持久化不完善。xerj 的 FileRaftLog 用"先 fsync 后入内存"的次序和批量刷盘策略处理了重启恢复问题;
  3. 分片管理必须自动化:Qdrant 的分片迁移竞态、无法修改副本因子、磁盘满后重平衡失败,都需要人工介入。xerj 的 region 拆分/合并/再平衡 + Jump Consistent Hash 路由,正是朝着"自动分片、无需人工干预"方向的实现。

最后回到能力边界:xerj 集群模式的现状是"领导者选举环 + 认证传输 + 持久化共识日志",索引与文档仍是节点本地数据。将本文所引源码(raft.rs、raft_log.rs、replication.rs、regions.rs)与官方现状文档(landing/docs/clustering.html)对照阅读,即可获得对"哪些是已实现、哪些是设计先行"的准确判断——这也是评估任何向量搜索数据库集群方案时最值得养成的习惯。

登录后查看全文
xerj