企业官网建设流程全解析

Quickwit 0.9 升级指南：破坏性变更、Ingest V2 迁移与回滚策略

【免费下载链接】quickwitCloud-native OSS search engine for observability项目地址: https://gitcode.com/GitHub_Trending/qu/quickwit

本篇指南以 docs/get-started/upgrade.md 为核心，系统梳理从 Quickwit 0.8.x 升级到 0.9 的完整路径：升级前的备份与停机准备、Ingest V2 的启用与回退方式、配置项迁移、指标名变更以及源码构建工具链要求，并结合当前仓库的源码与配置逐项印证。读完本文，你将掌握一套可执行的升级操作清单、回滚方案，以及升级后因分片提交模型变化而需要的 merge 策略调优手段。

说明：本文所有命令与配置均以当前仓库的实际内容为准。若你跨多个 minor 版本升级，请按顺序依次执行每个中间版本对应的迁移步骤。

一、升级前准备：三条必做动作

Quickwit 0.9 在首次启动时会运行 SQL 迁移，向 metastore 中新增maturity与 compaction 相关字段列。一旦迁移执行，旧版本将无法直接读取，因此升级前的备份是回滚的唯一保障。

1. 备份 metastore（必做）

根据 metastore 类型选择备份方式：

• PostgreSQL metastore：对数据库做快照（snapshot）。0.9 的 SQL 迁移发生在第一次启动时，迁移后旧版本无法直接识别新 schema。
• file-backed metastore：保留一份indexes/目录的副本。该目录即文件型 metastore 的状态本体，升级前完整拷贝一份即可。

2. 备份索引数据（可选但推荐）

0.9 不改变磁盘上的 split 格式与对象存储布局，因此无需重新索引（re-index）。但如果你的存储后端本身没有开启版本管理（如 S3 版本控制），建议仍做一次数据备份，作为额外保险。

3. 停止所有 0.8.x 节点后再启动任何 0.9 节点

迁移期间不支持混版本集群（mixed-version cluster）。请先全量停掉旧节点，再逐步启动新节点。官方在 docs/operating/upgrades.md 中进一步给出了 0.8 → 0.9 全集群重启的推荐顺序：

• 关闭顺序：indexers、searchers、janitor → control plane → metastores；
• 启动顺序：metastores → control plane → indexers、searchers、janitor。

这一顺序在升级到 0.9 时被官方明确推荐，原因是 0.9 重新设计了索引计划的计算方式，control plane 升级时所有 indexing pipeline 都会重启，旧节点上已写入但尚未被 pickup 的数据只有在新 control plane 就位后才会被消费。

二、Ingest V2：默认启用的新摄取服务

0.9 的最大行为变更来自新的摄取服务（Ingest V2），它驱动着 ingest 与 bulk API。理解它的开关矩阵与路由变化，是本次升级的核心。

1. 从 opt-in 到默认启用

在 0.8.x 中，Ingest V2 需要通过环境变量QW_ENABLE_INGEST_V2=true手动开启，并且走独立的专用路由POST /api/v1/{index}/ingest-v2。

在 0.9 中：

• QW_ENABLE_INGEST_V2默认值为true；
• POST /api/v1/{index}/ingest自动路由到 V2；
• 专用路由POST /api/v1/{index}/ingest-v2已被移除；
• V1 仍然保留在内部：可通过请求参数?use_legacy_ingest=true逐请求回退，也可通过QW_ENABLE_INGEST_V2=false在集群范围内整体回退；
• QW_DISABLE_INGEST_V1=true可以在所有客户端完成迁移后强制纯 V2 运行。

上述行为在源码中有直接对应实现：quickwit/quickwit-config/src/lib.rs 中的enable_ingest_v2()与disable_ingest_v1()分别读取这两个环境变量，默认值即true与false；quickwit/quickwit-serve/src/ingest_api/rest_handler.rs 在 V2 启用且未请求 legacy 时会校验QW_DISABLE_INGEST_V1，若 V1 被禁用则直接返回错误提示；quickwit/quickwit-rest-client/src/rest_client.rs 则在客户端请求中注入use_legacy_ingest=true查询参数。该机制同样作用于 Elasticsearch 兼容的 bulk API，见 quickwit/quickwit-serve/src/elasticsearch_api/bulk.rs。集成测试 quickwit/quickwit-integration-tests/src/tests/ingest_v1_tests.rs 通过use_legacy_ingest()显式构造 V1 场景来验证兼容路径。

可将开关矩阵总结如下：

2. 操作影响：更多、更小的 split

Ingest V2 会将提交（commit）分散到多个并行运行的 indexer 上按分片（shard）处理。因此在一个刚刚停止写入的 ingest 流上，你可能会观察到比 V1 更多、也更小的 split——因为每个分片的尾部 split 不一定能达到 merge policy 的merge_factor阈值，从而滞留在"未合并"状态。

如果你对稳态 split 数量有较低的要求，可以在索引配置中调低indexing_settings.merge_policy.merge_factor（例如调到2），或者主动运行 merge-on-demand 路径。从当前仓库的 quickwit/quickwit-config/src/merge_policy_config.rs 可以看到默认值为merge_factor = 10、max_merge_factor = 12，三种内置 merge policy（ConstWriteAmplification、StableLog、Parquet）均复用这两个默认值，并在配置校验中要求max_merge_factor >= merge_factor。调低merge_factor意味着更早触发小规模合并，有助于压低尾部 split 的滞留数量，代价是合并次数增加。

3. 双版本并存的磁盘占用注意

在 0.9 中，虽然 V2 默认启用，但 V1 仍然保留以消化 legacy write-ahead log 中的残余数据。因此需要注意：docs/operating/upgrades.md 明确指出，ingest_api.max_queue_disk_usage会在 V1 与 V2 两个版本上分别强制执行，也就是说两者的累计磁盘占用可能达到该上限的两倍。规划磁盘容量时务必预留这部分空间。相关默认值可在 quickwit/quickwit-config/src/node_config/mod.rs 的IngestApiConfig中确认：max_queue_memory_usage默认 2 GiB、max_queue_disk_usage默认 4 GiB、content_length_limit默认 10 MiB、decommission_timeout默认 300s；校验逻辑要求max_queue_disk_usage至少为 256 MiB 且不小于max_queue_memory_usage。

4. 启用 gRPC 压缩的两步升级

如果需要为 ingest 服务启用压缩（ingest_api.grpc_compression_algorithm，例如zstd），官方建议分两步执行：先以压缩关闭状态升级 indexer 节点，然后更新节点配置开启压缩，最后再重启 indexer 节点。该字段类型为Option<CompressionAlgorithm>，默认关闭，见 quickwit/quickwit-config/src/node_config/mod.rs。

三、配置变更：rest_listen_port 迁移与新 feature 开关

1.rest_listen_port弃用，迁入rest块

顶层字段rest_listen_port已被标记为弃用，需要迁移到新的rest配置块下：

# before (0.8.x, 0.9 中仍可用，但会打印弃用警告) rest_listen_port: 7280 # after (0.9) rest: listen_port: 7280

旧字段在整个 0.9 周期内仍然生效以降低迁移成本，但计划在 0.10 移除，升级后应尽快完成迁移。RestConfig的完整结构可在 quickwit/quickwit-config/src/node_config/mod.rs 中查看，除listen_addr外还支持cors_allow_origins、extra_headers、tls、max_connection_age等字段。仓库自带的 config/quickwit.yaml 示例注释同样已采用新写法：

# rest: # listen_port: 7280 # cors_allow_origins: # - "http://localhost:3000" # extra_headers: # x-header-1: header-value-1

2. Stemming 需要multilangcargo feature

如果你从源码自行构建 Quickwit 且依赖词干化（stemming）能力，构建时需要显式添加--features multilang。官方发布的二进制与 Docker 镜像均已启用该 feature，因此使用发行镜像的用户不受影响。

同时，原先独立的multilangtokenizerfeature（注意与上面的multilangcargo feature 是两回事）已被移除。如果你自定义过 doc mapper 并引用了它，需要切换到标准 tokenizer。

3. Rust 工具链要求（仅源码构建）

0.9 的源码构建要求 Rust1.92（升级文档记载该版本）。需要说明的是，当前仓库的 quickwit/rust-toolchain.toml 已演进为channel = "1.96"，说明后续开发版本的工具链要求进一步提升。因此源码构建前，请务必以仓库内rust-toolchain.toml文件为准，使用 rustup 自动下载对应工具链。使用官方 Docker 镜像或预编译二进制的用户无需关心此项。

四、指标名变更：dashboard 与告警需要同步调整

0.9 将指标采集切换到了metrics-rs埋点栈。绝大多数指标名保持不变，但有两组指标发生变化，涉及 Grafana dashboard 与告警规则的更新：

1. gRPC 指标改用servicelabel，服务名不再内嵌在指标名中：

   变更前	变更后
   quickwit_<service>_grpc_requests_total	quickwit_grpc_requests_total{service="<service>"}
   quickwit_<service>_grpc_requests_in_flight	quickwit_grpc_requests_in_flight{service="<service>"}
   quickwit_<service>_grpc_request_duration_seconds	quickwit_grpc_request_duration_seconds{service="<service>"}

2. Janitor GC 指标不再带有重复的quickwit_前缀：旧命名空间中quickwit_quickwit_janitor_gc_deleted_bytes_total一类的指标名修正为quickwit_janitor_gc_deleted_bytes_total。

如果你的监控体系（如仓库 monitoring/grafana/dashboards 下的 searchers、indexers、metastore 等 dashboard）直接引用了上述旧指标名，请按新命名改写查询表达式。

五、回滚策略：metastore 回滚是单向的

需要特别强调：metastore 的回滚是单向的（one-way）。0.9 启动时执行的 SQL 迁移（新增maturity、compaction 相关列）无法通过降级自动撤销。

如果必须回退到 0.8.x：

1. 关闭所有 0.9 节点；
2. 使用升级前第一步保存的 metastore 备份恢复（PostgreSQL 快照或indexes/目录副本）；
3. 在恢复后的 metastore 之上启动 0.8.x 节点。

回滚期间同样不允许混版本运行。

六、跨多版本升级与更多历史迁移说明

若你从更早的版本升级，请按版本顺序逐个执行。仓库 docs/operating/upgrades.md 还记录了更早版本的迁移要点，可作为参考：

• 0.6.x → 0.7.0：索引与 metastore 内部对象格式向后兼容；若使用otel-logs-v0_6、otel-traces-v0_6索引，需先停止写入，因为 0.7 首次启动会自动将这两个索引的 Trace ID / Span ID 字段格式从base64改为hex；同时会创建新索引otel-traces-v0_7。
• 0.7.0 → 0.7.1：新增otel-logs-v0_7默认索引；若otel-traces-v0_7已存在则不做迁移，如需service_name字段为fast，需先删除该索引或自行建索引。
• 历史版本的破坏性变更清单可查阅仓库根目录的 CHANGELOG.md。

七、升级自检清单

遵循以上步骤，即可在保留回滚能力的前提下平滑完成 0.8 → 0.9 的迁移，并在升级后根据 Ingest V2 的提交模型调整索引策略与监控告警。

【免费下载链接】quickwitCloud-native OSS search engine for observability项目地址: https://gitcode.com/GitHub_Trending/qu/quickwit