Grafana Mimir 3.0 版本发布指南：Kafka 摄取存储架构、MQE 默认查询引擎与升级要点-平芜编程栈

时序数据库
后端
数据存储
可观测性
云原生

【免费下载链接】mimir

Grafana Mimir provides horizontally scalable, highly available, multi-tenant, long-term storage for Prometheus.

项目地址：https://gitcode.com/gh_mirrors/mimir/mimir

导读

本文以 Grafana Mimir v3.0 release notes 为骨架，系统讲解该版本的两大核心里程碑：基于 Kafka 的ingest storage（摄取存储）架构与成为默认查询引擎的Mimir Query Engine（MQE），同时完整覆盖 3.0 引入的重要变更、实验性功能与已知问题。读完本文，你将理解 3.0 的架构演进动机、MQE 相比 Prometheus 引擎的流式执行原理，掌握启用 Kafka 摄取存储、切换/回退查询引擎、开启集群校验等实战配置方法，并能在升级前完成针对性的兼容性检查。

一、Grafana Mimir 3.0 概览

Grafana Labs 于 3.0 版本正式发布 Grafana Mimir（以下行文简称 Mimir），其定位依然是：为 Prometheus 提供水平可扩展、高可用、多租户、长期存储的时序数据库（参见仓库根目录 README.md 中的项目描述）。

本版的主要亮点可概括为三条主线：

引入 ingest storage 架构：通过 Kafka 将读写路径解耦，读写可独立伸缩；
MQE 全面转正：Mimir Query Engine 成为 querier 与 query-frontend 的默认查询引擎；
大规模清理：删除若干已废弃的实验性标志与部署模式，并对默认行为做了一系列收敛。

对于完整的变更列表，官方建议直接查阅仓库根目录的 CHANGELOG.md（其中## 3.0.0一节自 CHANGELOG.md 第 922 行起逐条记录了本次发布的所有 CHANGE / FEATURE / ENHANCEMENT / BUGFIX）。

二、核心特性一：Ingest storage 架构

2.1 为什么引入 Kafka 摄取层

在 Mimir 3.0 之前的经典架构（classic architecture）中，ingester 同时承担写入与查询两条链路：既要接收并暂存样本，又要响应 querier 的查询请求。在大查询负载下，读写双方会争抢 ingester 的 CPU、内存与网络资源，产生相互拖累。

ingest storage 架构的核心思路是：在写入端与查询端之间引入 Kafka 作为异步缓冲层。写入路径变为：

distributor将租户数据写入 Kafka 主题；
ingester作为 Kafka 消费者持续拉取分区数据并落盘到 TSDB；
查询时 querier 只与 ingester（以及 store-gateway）交互，不再触碰写入链路。

由此，读与写可以独立水平伸缩：写扩容只需增加 Kafka 分区与消费能力，读扩容只需增加 querier/ingester 副本。官方 release notes 明确其收益包括：提升写入稳定性、改善查询性能、增强大规模部署的运维灵活性。

重要前提：在 Mimir 3.0 中，经典架构依然受支持（"classic architecture is still supported"），用户不必强制迁移。同时，官方在 Kafka 后端配置文档中明确：从 3.0 起，ingest storage 是运行 Mimir 的首选（preferred）且稳定（stable）的架构。

2.2 如何启用 Kafka 摄取存储

Kafka 后端需要显式开启，且所有 Mimir 组件都必须统一启用，否则组件间数据流会不一致。核心配置标志如下（出处：configure-kafka-backend.md）：

配置标志	含义
`-ingest-storage.enabled=true`	显式启用 ingest storage 架构（所有组件都要设置）
`-ingest-storage.kafka.address=<host:port>[,<host:port>...]`	Kafka seed broker 地址，可配置逗号分隔的多个地址以提升引导可用性
`-ingest-storage.kafka.topic=<name>`	用于摄取数据的 Kafka 主题名
`-ingest-storage.kafka.auto-create-topic-default-partitions=<number>`	主题不存在时，消费者/生产者首次访问会自动创建；该数字为自动创建时的分区数，至少应等于一个 zone 内的 ingester 数量

另外官方推荐配合调整：

-distributor.remote-timeout=5s：把默认的 remote write 超时调大，因为写入 Kafka（尤其是 Kafka 兼容后端）可能比直写 ingester 更慢。

从源码看，该特性在配置结构上集中定义于 pkg/mimir/mimir.go 的IngestStorage字段（第 130 行）（类型为ingest.Config），并在 mimir.go 第 207 行注册标志、第 295 行做合法性校验。校验逻辑中还包含一条关键约束：只有启用了 ingest storage，才允许关闭 ingester 的 Push gRPC 方法（见 mimir.go 第 351-352 行），因为启用摄取存储后 ingester 只应通过 Kafka 接收数据——这也印证了该架构"读写分离"的设计初衷。

2.3 不同 Kafka 后端的适配

Mimir 3.0 支持对接多种 Kafka 兼容实现，各自需要的额外配置如下：

Apache Kafka 与 Confluent Kafka：Mimir 默认的-ingest-storage.kafka.producer-max-record-size-bytes约为15.2 MB，而两者默认message.max.bytes仅为1 MB。需要在 broker 配置（如server.properties）中调大：

message.max.bytes=16000000

也可按主题粒度调整：

bin/kafka-configs.sh --bootstrap-server <host:port> \ --alter --entity-type topics --entity-name <topic-name> \ --add-config max.message.bytes=16000000

Warpstream：

-ingest-storage.kafka.use-compressed-bytes-as-fetch-max-bytes=false

2.4 Kafka 认证与传输安全

Mimir 3.0 的 Kafka 客户端支持丰富的认证方式，绝大多数基于 SASL 框架：

PLAIN / SCRAM-SHA-256 / SCRAM-SHA-512：用户名 + 密码认证，对应标志-ingest-storage.kafka.sasl-mechanism、-ingest-storage.kafka.sasl-username、-ingest-storage.kafka.sasl-password。默认机制为PLAIN；为向后兼容，PLAIN 机制下不配用户名与密码即视为禁用 SASL。
OAUTHBEARER：OAuth 2.0 Bearer Token，静态配置可用-ingest-storage.kafka.sasl-oauthbearer-token、-ingest-storage.kafka.sasl-oauthbearer-zid、-ingest-storage.kafka.sasl-oauthbearer-extensions（可选）；动态刷新可走 JSON 配置文件或 HTTP 回调。
AWS_MSK_IAM：面向 Amazon MSK 的 IAM 认证，静态配置用-ingest-storage.kafka.sasl-msk-iam-access-key、-ingest-storage.kafka.sasl-msk-iam-secret-key、-ingest-storage.kafka.sasl-msk-iam-session-token（可选）、-ingest-storage.kafka.sasl-msk-iam-user-agent（可选）。

动态刷新两种方式：

配置文件：-ingest-storage.kafka.sasl-<oauthbearer|msk-iam>-file-path，JSON 形状分别对应{"token": "...", "zid": "...", "extensions": {...}}与{"AccessKey": "...", "SecretKey": "...", "SessionToken": "...", "UserAgent": "..."}（仅 token/AccessKey+SecretKey 为必填）。每次需要重新认证时会重新读取该文件，Mimir 不会主动通知刷新时机，凭据生命周期与文件更新需自行在带外处理。
HTTP 回调：-ingest-storage.kafka.sasl-<mechanism>-http-socket-path指定 Unix domain socket 路径，超时可用-ingest-storage.kafka.sasl-<mechanism>-http-socket-timeout配置（默认10s）。服务端收到对/的 HTTP GET 后需返回 200 及上述 JSON 对象。相比静态配置与文件方式，HTTP 回调无需带外管理凭据生命周期，凭据也不必持久化，按需动态下发。

传输加密方面：

-ingest-storage.kafka.tls-enabled=true开启 TLS；
需要 mTLS 时追加-ingest-storage.kafka.tls-ca-path（CA 证书，缺省用系统根 CA）、-ingest-storage.kafka.tls-cert-path与-ingest-storage.kafka.tls-key-path（两者须成对配置）；
可选-ingest-storage.kafka.tls-server-name（覆盖服务端证书预期名称）、-ingest-storage.kafka.tls-insecure-skip-verify（仅测试用）、以及-ingest-storage.kafka.tls-cipher-suites、-ingest-storage.kafka.tls-min-version等进阶项。

2.5 摄取存储架构下的行为差异

结合仓库源码与文档，启用 ingest storage 后部分机制的行为会发生变化，升级运维时需注意：

Push gRPC 方法可关闭：ingester 只从 Kafka 接收数据时，可关闭-ingester.push-grpc-method-enabled（见 pkg/ingester/ingester.go 第 247 行的注释说明）；
owned series 追踪方式改变：在摄取存储架构中，token 被分配给partition而非 ingester，序列的复制由 Kafka 分区机制承载，因此经典架构所需的 owned series 配置步骤可以省略（见 configure-owned-series.md）；
部分限流器不适用：Push 请求的 circuit breaker 与 reactive limiter 在摄取存储架构中不可用（分别见 about-ingester-circuit-breakers.md 与 about-reactive-limiters.md）；
shuffle sharding 转向分区维度：写读路径的分区级 shuffle sharding 见 configure-shuffle-sharding/index.md。

三、核心特性二：Mimir Query Engine（MQE）成为默认引擎

3.1 MQE 是什么

Mimir Query Engine（MQE）是 Mimir 自研的 PromQL 查询引擎，位于 pkg/streamingpromql/（其设计说明见 pkg/streamingpromql/README.md）。它的目标是在安全、高性能、低成本的前提下求值涉及数百万条序列的查询，核心手段是流式（streaming）执行：

关键思路是不一次性把所有输入序列载入内存，而是在需要时才按需流式读入。

官方 release notes 给出的量化收益是：相比 Prometheus 引擎，峰值内存占用最高可降低 92%，从而在大负载下获得更快、更稳的查询性能与更低资源消耗。

其原理可借助一个具体例子说明（原文来自 pkg/streamingpromql/README.md）：查询sum by (environment) (some_metric{cluster="cluster-1"})。

Prometheus 引擎：先把选择器命中的所有序列的全部样本一次性载入内存，再逐组求和；峰值时同时持有全部输入序列样本与全部输出序列样本。
MQE：先执行选择器、收集全部序列的标签，据此预先计算出sum by (environment)的全部可能输出序列（environment 每个取值一条），然后逐条读入输入序列、累加到对应输出序列；峰值时只持有一条输入序列的样本与所有输出序列的样本。

更复杂的查询可以逐级流式传递：如max(sum by (environment) (...))，每当一个sum分组结果完整产出，立即交给max更新当前最大值（详见 README 中的 mermaid 查询计划图）。在 MQE 内部，每条查询被表示为一系列串联的 operator（如 instant vector selector、sum 聚合、max 聚合），它们满足InstantVectorOperator接口，通过SeriesMetadata()与NextSeries()两个核心方法逐系列产出数据。

3.2 默认引擎与切换方式

从2.17开始，MQE 已是 querier 的默认引擎（见 v2.17 release notes）；到3.0，query-frontend 也默认使用 MQE（CHANGELOG.md 第 935 行），即 MQE 成为所有 querier 与 query-frontend 的默认引擎。

MQE 与 Prometheus 引擎的取值常量定义于 pkg/querier/querier.go 第 94-95 行：PrometheusEngine = "prometheus"、MimirEngine = "mimir"；
切换引擎的标志在 querier.go 第 115 行注册：-querier.query-engine=<mimir|prometheus>，默认值为mimir。若想继续使用 Prometheus 引擎，按 release notes 明确说明设置：

-querier.query-engine=prometheus

校验逻辑见 querier.go 第 126-128 行：传入其他值会直接报unknown PromQL engine错误；
引擎实际构建分支在 querier.go 第 211-221 行附近：prometheus走promql.NewEngine(...)，mimir走streamingpromql.NewEngine(...)。

3.3 引擎回退机制

MQE 当前仍非 100% 覆盖所有 PromQL 语法，因此 Mimir 提供了回退机制：

-querier.enable-query-engine-fallback：默认true。当 MQE 遇到不支持的查询时，自动回退到 Prometheus 引擎执行（注册于 querier.go 第 116 行）。这也是 MQE 全面转正后能保持稳定兼容的关键保障。

3.4 MQE 相关增强（3.0 新增）

从 CHANGELOG.md 的 3.0.0 记录看，本版对 MQE 的强化集中在：

直方图查询优化：query-frontend.rewrite-histogram-queries新增 MQE AST 优化 pass，重写直方图查询为更高效的执行顺序（CHANGELOG.md 第 955 行）；
查询重写优化：query-frontend.rewrite-propagate-matchers在二元运算间复制相关 label matcher（CHANGELOG.md 第 954 行）；
查询计划改进：querier 与 query-frontend 支持在前端进行查询计划（query planning）并分发计划片段给 querier 执行（CHANGELOG.md 第 963 行）；
公共子表达式消除（CSE）扩展至即时查询的 range vector 表达式（CHANGELOG.md 第 977 行）；
新增实验性 PromQL 函数支持：mad_over_time、ts_of_min_over_time等（CHANGELOG.md 第 968-970 行）；
查询前端 MQE 相关标志：querier.mimir-query-engine.enable-prune-toggles取代旧的query-frontend.prune-queries（CHANGELOG.md 第 933 行）。

四、其他关键增强

3.0 除两大主线外，还包含以下值得关注的变化：

HA tracker 默认后端切换为 memberlist：distributor 的 HA tracker 默认使用 memberlist 而非 etcd/consul，etcd 与 consul 虽仍支持但已标记废弃（CHANGELOG.md 第 948、1008 行）；
Store-gateway 动态复制因子默认值提高：-store-gateway.dynamic-replication.multiple默认改为5，以增强近期 block 的复制（CHANGELOG.md 第 940 行）；
UTF-8 标签/指标名支持扩展：cardinality 相关 API 端点与label_join、label_replace、count_values等函数支持 UTF-8 命名（CHANGELOG.md 第 927-928 行）；
Ruler 远程评估：支持使用 Prometheus 兼容 HTTP 端点做远程规则评估（remote evaluation mode），可用于多实例联邦（CHANGELOG.md 第 952 行）；
缓存与依赖清理：移除 Redis 缓存后端支持（CHANGELOG.md 第 929 行）；
成本归因（cost attribution）：每用户标签基数默认上限降至 2000（CHANGELOG.md 第 941 行）。

五、重要变更与升级注意事项

升级到 3.0 前，务必逐一核对下列行为变化（release notes 的 "Important changes" 一节）：

ingest storage 架构引入：数据流在组件间发生变化，读写分离；启用前需先备好 Kafka 后端与分区规划。
MQE 成为默认引擎：若不希望使用 MQE，必须显式设置-querier.query-engine=prometheus（注意 2.17 中-query-frontend.query-engine是实验性标志，3.0 前端已默认 MQE）。
实验性功能移除：
- read-write 部署模式被移除（CHANGELOG.md 第 939 行，对应 2.17 中 mixin 的 read-write 模式也早已移除）；
- query-frontend 的-query-frontend.downstream-url（代理任意 Prometheus 后端）被移除（CHANGELOG.md 第 931 行）；
- 实验性 instant query splitting 被移除（CHANGELOG.md 第 932 行）；
- 废弃的-ingester.stream-chunks-when-using-blocks等标志被清理（CHANGELOG.md 第 937 行）。
配置清理与结构调整：
- query-scheduler 成为必选组件：-querier.frontend-address、-querier.max-outstanding-requests-per-tenant、-query-frontend.querier-forget-delay被移除，不再支持前端内嵌 query-scheduler（CHANGELOG.md 第 936 行）；
- 流式查询成为强制路径：-querier.streaming-chunks-per-ingester-buffer-size等必须为非零值（CHANGELOG.md 第 938 行）；
- Redis 缓存后端不再可用（CHANGELOG.md 第 929 行）；
- 移除非标准 HTTP 529 限流状态码选项，统一用 429（CHANGELOG.md 第 943 行）。

六、实验性功能（Experimental features）

3.0 中以下功能仍处于实验阶段，官方建议谨慎使用并及时反馈问题：

实验性功能	启用方式与说明
Prometheus Remote-Write 2.0 协议	通过 HTTP`Content-Type: application/x-protobuf; proto=io.prometheus.write.v2.Request`识别（见 pkg/distributor/push.go 第 273-304 行的`isRemoteWrite2`实现；未设置 Content-Type 或 proto 为`prometheus.WriteRequest`时按 v1 处理）
PromQL duration 表达式	允许在 range 或 offset 值中做简单算术，例如`rate(http_requests_total[5m * 2])`
HTTP 集群校验（默认关闭）	通过`-server.cluster-validation.*`系列标志启用（见下）
Native OTLP delta 指标摄取（默认关闭）	`-distributor.otel-native-delta-ingestion`，启用后直接存储原始 delta 采样值，禁用时拒绝 delta 指标（见 pkg/util/validation/limits.go 第 429 行）

6.1 HTTP 集群校验配置详解

集群校验（cluster validation）用于让 HTTP/gRPC 服务端校验请求是否来自预期集群，在集群迁移等场景下防止跨集群误写。配置模型定义于 dskit 的 vendor/github.com/grafana/dskit/clusterutil/cluster_validation_config.go，关键配置项：

-server.cluster-validation.label：主集群标签（label）；
-server.cluster-validation.additional-labels：迁移期间可额外接受的多余标签（需先设置主 label，见该文件第 49-53 行的校验）；
-server.cluster-validation.http.enabled：启用 HTTP 校验（默认关闭）；
-server.cluster-validation.http.soft-validation：软校验模式，仅可伴随 enabled 开启；
-server.cluster-validation.http.exclude-paths、-server.cluster-validation.http.exclude-user-agents：从校验中排除的路径 / User-Agent；
-server.cluster-validation.grpc.enabled等：gRPC 侧对应配置。

客户端侧（gRPC 调用方）也可配置自己的集群标签，例如 pkg/frontend/config.go 第 49 行的-query-frontend.client-cluster-validation.label，以及 pkg/mimir/mimir.go 第 901 行的公共配置前缀-common.client-cluster-validation.*。完整的各类客户端前缀可见 pkg/mimir/mimir_config_test.go 第 90-93 行中的测试用例。

七、Bug fixes 与 Helm chart 说明

官方 release notes 明确：完整的 bug 修复列表请查阅 CHANGELOG.md 的 3.0.0 记录。其中值得注意的修复类型包括：

Remote-Write 2.0 相关：修复零时间序列请求导致的 nil 指针 panic（CHANGELOG.md 第 879 行）、修复WriteResponseStats统计差异（CHANGELOG.md 第 1014 行）、修复 RW2 请求中 Unknown 类型 metric metadata 被静默丢弃（CHANGELOG.md 第 1022 行）；
MQE 查询正确性：修复label_join错误信息引用源标签名错误（CHANGELOG.md 第 1041 行）；
摄取存储：修复 fetcher 从 Kafka 请求超限字节数等问题（CHANGELOG.md 第 1025 行）；
一般稳定性：querier 对同时间戳样本确定性合并（CHANGELOG.md 第 1016 行）、store-gateway 潜在 goroutine 泄漏（CHANGELOG.md 第 1017 行）等。

此外需要特别注意：Grafana Mimir 的 Helm chart 是独立发布、独立版本化的，因此 3.0 的 release notes 不包含 Helm chart 的变更明细，请查阅独立的 Helm chart 文档（仓库内的 Helm chart 位于 operations/helm/charts/）。

八、从源码继续深入

如果希望进一步验证本文涉及的技术细节，建议直接在仓库中查看以下位置：

摄取存储配置：pkg/mimir/mimir.go 第 130、207、295、351 行（配置挂载与校验）、docs/sources/mimir/configure/configure-kafka-backend.md（完整 Kafka 配置指南）；
MQE 实现与原理：pkg/streamingpromql/README.md（流式执行原理与查询计划示例）、pkg/querier/querier.go 第 94-128、199-221 行（引擎选择与回退）；
RW2 协议识别：pkg/distributor/push.go 第 273-304 行；
OTLP delta 摄取：pkg/util/validation/limits.go 第 429 行；
集群校验实现：vendor/github.com/grafana/dskit/clusterutil/cluster_validation_config.go；
完整变更清单：CHANGELOG.md 第 922 行起（3.0.0 条目）。

总结

Grafana Mimir 3.0 是一次"架构级"的版本升级：Kafka 摄取存储把读写路径彻底解耦，MQE 以流式执行成为默认查询引擎并显著压低峰值内存，同时通过移除 read-write 模式、废弃 Redis 缓存、强制 query-scheduler 等方式收敛了历史包袱。对于运维团队，升级前请重点核对 Kafka 后端可用性、MQE 回退策略、query-scheduler 部署以及各类已移除标志的清理；对于开发与调优场景，则可从-ingest-storage.*与-querier.query-engine两组配置入手，结合 CHANGELOG.md 逐步验证 3.0 的各项行为变化。