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_V2true手动开启并且走独立的专用路由POST /api/v1/{index}/ingest-v2。在 0.9 中QW_ENABLE_INGEST_V2默认值为truePOST /api/v1/{index}/ingest自动路由到 V2专用路由POST /api/v1/{index}/ingest-v2已被移除V1 仍然保留在内部可通过请求参数?use_legacy_ingesttrue逐请求回退也可通过QW_ENABLE_INGEST_V2false在集群范围内整体回退QW_DISABLE_INGEST_V1true可以在所有客户端完成迁移后强制纯 V2 运行。上述行为在源码中有直接对应实现quickwit/quickwit-config/src/lib.rs 中的enable_ingest_v2()与disable_ingest_v1()分别读取这两个环境变量默认值即true与falsequickwit/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_ingesttrue查询参数。该机制同样作用于 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 场景来验证兼容路径。可将开关矩阵总结如下场景配置方式生效范围默认0.9 起不设置任何变量集群使用 V2逐请求回退 V1请求带?use_legacy_ingesttrue单个请求集群回退 V1QW_ENABLE_INGEST_V2false整个集群强制纯 V2QW_DISABLE_INGEST_V1true整个集群V1 请求报错2. 操作影响更多、更小的 splitIngest 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 policyConstWriteAmplification、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 节点。该字段类型为OptionCompressionAlgorithm默认关闭见 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-12. 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 与告警规则的更新gRPC 指标改用servicelabel服务名不再内嵌在指标名中变更前变更后quickwit_service_grpc_requests_totalquickwit_grpc_requests_total{serviceservice}quickwit_service_grpc_requests_in_flightquickwit_grpc_requests_in_flight{serviceservice}quickwit_service_grpc_request_duration_secondsquickwit_grpc_request_duration_seconds{serviceservice}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关闭所有 0.9 节点使用升级前第一步保存的 metastore 备份恢复PostgreSQL 快照或indexes/目录副本在恢复后的 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。七、升级自检清单检查项操作依据metastore 备份PostgreSQL 快照或拷贝indexes/目录docs/get-started/upgrade.md索引数据备份可选存储后端无版本管理时建议备份同上停机顺序indexers/searchers/janitor → control plane → metastoresdocs/operating/upgrades.md启动顺序metastores → control plane → indexers/searchers/janitor同上客户端兼容确认客户端支持 V2或评估use_legacy_ingesttrue/QW_ENABLE_INGEST_V2false过渡期quickwit/quickwit-config/src/lib.rs磁盘容量预留ingest_api.max_queue_disk_usage两倍的 V1/V2 并存空间docs/operating/upgrades.md配置迁移rest_listen_port→rest.listen_port确认无弃用警告config/quickwit.yaml源码构建确认 Rust 版本满足rust-toolchain.toml按需--features multilangquickwit/rust-toolchain.toml监控更新按新命名改写 gRPC 与 Janitor GC 指标查询本文第四节稳态 split 数按需调低merge_factor如2或执行 merge-on-demandquickwit/quickwit-config/src/merge_policy_config.rs遵循以上步骤即可在保留回滚能力的前提下平滑完成 0.8 → 0.9 的迁移并在升级后根据 Ingest V2 的提交模型调整索引策略与监控告警。【免费下载链接】quickwitCloud-native OSS search engine for observability项目地址: https://gitcode.com/GitHub_Trending/qu/quickwit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Quickwit 0.9 升级指南：破坏性变更、Ingest V2 迁移与回滚策略
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_V2true手动开启并且走独立的专用路由POST /api/v1/{index}/ingest-v2。在 0.9 中QW_ENABLE_INGEST_V2默认值为truePOST /api/v1/{index}/ingest自动路由到 V2专用路由POST /api/v1/{index}/ingest-v2已被移除V1 仍然保留在内部可通过请求参数?use_legacy_ingesttrue逐请求回退也可通过QW_ENABLE_INGEST_V2false在集群范围内整体回退QW_DISABLE_INGEST_V1true可以在所有客户端完成迁移后强制纯 V2 运行。上述行为在源码中有直接对应实现quickwit/quickwit-config/src/lib.rs 中的enable_ingest_v2()与disable_ingest_v1()分别读取这两个环境变量默认值即true与falsequickwit/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_ingesttrue查询参数。该机制同样作用于 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 场景来验证兼容路径。可将开关矩阵总结如下场景配置方式生效范围默认0.9 起不设置任何变量集群使用 V2逐请求回退 V1请求带?use_legacy_ingesttrue单个请求集群回退 V1QW_ENABLE_INGEST_V2false整个集群强制纯 V2QW_DISABLE_INGEST_V1true整个集群V1 请求报错2. 操作影响更多、更小的 splitIngest 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 policyConstWriteAmplification、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 节点。该字段类型为OptionCompressionAlgorithm默认关闭见 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-12. 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 与告警规则的更新gRPC 指标改用servicelabel服务名不再内嵌在指标名中变更前变更后quickwit_service_grpc_requests_totalquickwit_grpc_requests_total{serviceservice}quickwit_service_grpc_requests_in_flightquickwit_grpc_requests_in_flight{serviceservice}quickwit_service_grpc_request_duration_secondsquickwit_grpc_request_duration_seconds{serviceservice}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关闭所有 0.9 节点使用升级前第一步保存的 metastore 备份恢复PostgreSQL 快照或indexes/目录副本在恢复后的 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。七、升级自检清单检查项操作依据metastore 备份PostgreSQL 快照或拷贝indexes/目录docs/get-started/upgrade.md索引数据备份可选存储后端无版本管理时建议备份同上停机顺序indexers/searchers/janitor → control plane → metastoresdocs/operating/upgrades.md启动顺序metastores → control plane → indexers/searchers/janitor同上客户端兼容确认客户端支持 V2或评估use_legacy_ingesttrue/QW_ENABLE_INGEST_V2false过渡期quickwit/quickwit-config/src/lib.rs磁盘容量预留ingest_api.max_queue_disk_usage两倍的 V1/V2 并存空间docs/operating/upgrades.md配置迁移rest_listen_port→rest.listen_port确认无弃用警告config/quickwit.yaml源码构建确认 Rust 版本满足rust-toolchain.toml按需--features multilangquickwit/rust-toolchain.toml监控更新按新命名改写 gRPC 与 Janitor GC 指标查询本文第四节稳态 split 数按需调低merge_factor如2或执行 merge-on-demandquickwit/quickwit-config/src/merge_policy_config.rs遵循以上步骤即可在保留回滚能力的前提下平滑完成 0.8 → 0.9 的迁移并在升级后根据 Ingest V2 的提交模型调整索引策略与监控告警。【免费下载链接】quickwitCloud-native OSS search engine for observability项目地址: https://gitcode.com/GitHub_Trending/qu/quickwit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考