GreptimeDB 分布式元数据服务 meta-srv 架构深度解析心跳、选举、分布式过程与配置实战【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedbGreptimeDB 采用存算分离的分布式架构而meta-srv正是这套集群的元数据大脑它持久化集群/表/Region 元数据、负责 Leader 选举、驱动心跳循环追踪集群拓扑并编排 DDL、Region 迁移、Repartition 等分布式过程。本文以 src/meta-srv/AGENTS.md 为核心脉络结合meta-srvcrate 源码与 config/metasrv.example.toml 真实配置系统讲解其模块划分、核心流程、配置项语义、公开接口与测试方法帮助你理解并维护 GreptimeDB 的元数据服务层。meta-srv 在整个项目中的定位在分布式模式下GreptimeDB 由 Frontend、Datanode、Flownode 与 MetaSrv 共同组成。meta-srv承担元数据与协调职能具体包括持久化集群/表/Region 元数据所有元数据以 KV 形式写入后端存储默认 etcd跨节点共享Leader 选举在多个 MetaSrv 副本之间选出唯一 Leader保证写操作一致性心跳循环与集群拓扑追踪通过 Frontend/Datanode/Flownode 上报的心跳维护节点存活状态与集群拓扑分布式过程编排DDL建表/删表等、Region 迁移、Repartition 等操作以可恢复的过程Procedure形式执行。从 crate 依赖来看数据模型、KV 后端抽象、选举、Key 编码与 DDL 管理器都实现在common-metacrate 中meta-srv在其之上实现服务端、状态机与控制逻辑。分层遵循仓库级架构约束见 .agents/architecture-invariants.md 中common-* 不能反向依赖 storage engine、frontend、datanode、meta-srv的约定meta-srv通过common-meta、common-procedure等基础 crate 协作而不是重复实现元数据模型。模块地图meta-srv 源码导航meta-srv的源码全部位于 src/meta-srv/srcAGENTS.md 给出了清晰的模块导航表。下面按模块逐一说明其职责与关键文件模块路径职责bootstrapsrc/meta-srv/src/bootstrap.rs组装 KV 后端、选举、gRPC 服务与过程管理器完成进程启动metasrvsrc/meta-srv/src/metasrv.rs、src/meta-srv/src/metasrv/builder.rsMetasrv结构体、MetasrvOptions配置、MetasrvBuilder构建器与启动逻辑statesrc/meta-srv/src/state.rsLeader/Follower 状态机与状态迁移handlersrc/meta-srv/src/handler/心跳处理器链HeartbeatHandlerLeader 检查、Region 租约、统计、信箱servicesrc/meta-srv/src/service/gRPC 服务heartbeat、procedure、cluster、store与 HTTP admin 接口proceduresrc/meta-srv/src/procedure/分布式过程region_migration/、repartition.rs、wal_prune/regionsrc/meta-srv/src/region/Region 监督器、租约维护、故障转移触发discoverysrc/meta-srv/src/discovery/节点发现与基于租约的节点信息pubsubsrc/meta-srv/src/pubsub/心跳主题的发布/订阅支持gcsrc/meta-srv/src/gc/元数据驱动的垃圾回收过程与调度selectorsrc/meta-srv/src/selector/Region 放置策略round-robin / load-based / lease-basedpeersrc/meta-srv/src/peer.rs通过 selector 分配 Peerclustersrc/meta-srv/src/cluster.rsMetaPeerClient带 Leader 回退的内部 RPCcache_invalidatorsrc/meta-srv/src/cache_invalidator.rs向 Frontend/Datanode 推送缓存失效通知keysrc/meta-srv/src/key/MetaSrv 侧的 KV Key 编码bootstrap启动装配与 gRPC 路由bootstrap.rs中的MetasrvInstance::start()是进程启动的核心入口先启动 HTTP 服务再通过router()函数装配 gRPC 服务。从 src/meta-srv/src/bootstrap.rs 可以看出gRPC 路由依次注册了五个服务且全部开启 Gzip/Zstd 压缩与消息大小限制HeartbeatServer心跳服务接收 Frontend/Datanode/Flownode 的心跳流StoreServer元数据 KV 读写服务ClusterServer集群管理服务ProcedureServiceServer过程执行服务ConfigServer配置下发服务admin::make_admin_service兼容旧版的 admin 服务。后端选择逻辑见metasrv_builder()src/meta-srv/src/bootstrap.rs根据opts.backend决定使用MemoryKvBackend测试用、EtcdStore默认并同时构造EtcdElection或 PostgreSQL/MySQL需要对应 feature。stateLeader/Follower 状态机src/meta-srv/src/state.rs 中有一段 ASCII 状态图完整描述了状态迁移路径------------------------------ | | v | -------------------v-------------------- | | LeaderState{enable_leader_cache:false} | | --------------------------------------- | | | ---------v--------- | | Init Leader Cache | | ------------------ | | | -------------------v------------------- | | LeaderState{enable_leader_cache:true} | | -------------------------------------- | | | -------v------- | | FollowerState | | -------------- | | | ------------------------------关键语义新 Leader 上任时先进入enable_leader_cache: false状态此时禁用 Leader 缓存完成缓存初始化后切换为enable_leader_cache: true一旦发生 Leader 变更则回退为FollowerState。become_leader()与become_follower()两个函数src/meta-srv/src/state.rs正是上述迁移的具体实现。这正是 AGENTS.md 中Leader 使用在 Leader 变更时重置的缓存 KV 后端LeaderCachedKvBackend这一注意事项的状态机体现。核心流程四条主线AGENTS.md 归纳了四条核心流程下面结合源码逐一展开。心跳流程Heartbeat心跳是集群拓扑感知的基础。service/heartbeat.rs中的HeartbeatSession维护一条 gRPC 双向流收到首个心跳请求后校验RequestHeader并向HeartbeatHandlerGroup注册 pushersrc/meta-srv/src/service/heartbeat.rs循环select两条事件流上新的心跳消息、或 Leader 下台事件wait_leader_step_down。一旦通过选举订阅收到LeaderChangeMessage::StepDown立即向客户端返回 not leader 错误并终止会话src/meta-srv/src/service/heartbeat.rs响应中携带信箱mailbox消息用于下发 DDL 结果、缓存失效等指令。每个心跳请求会顺序穿过handler/下的处理器链。从 src/meta-srv/src/handler.rs 的add_default_handlers()可以看到默认链的完整组成顺序即执行顺序ResponseHeaderHandler— 写入响应头DatanodeKeepLeaseHandler/FlownodeKeepLeaseHandler— 续租节点租约CheckLeaderHandler— 仅 Leader 处理非 Leader 返回 not leaderOnLeaderStartHandler— Leader 上任初始化ExtractStatHandler— 提取节点统计CollectDatanodeClusterInfoHandler/CollectFrontendClusterInfoHandler/CollectFlownodeClusterInfoHandler— 采集各角色集群信息MailboxHandler— 处理信箱消息RegionLeaseHandler— Region 租约续期条件挂载FilterInactiveRegionStatsHandler— 过滤非活跃 Region 统计RegionFailureHandler— Region 故障处理开启 failover 时挂载PublishHeartbeatHandler— 向 pubsub 发布心跳开启时挂载CollectLeaderRegionHandler— 采集 Leader Region 信息CollectTopicStatsHandler— 采集 WAL 主题统计PersistStatsHandler— 持久化统计开启时挂载CollectStatsHandler— 汇总统计基于flush_stats_factor触发刷写RemapFlowPeerHandler— 流FlowPeer 重映射FlowStateHandler— 流状态处理条件挂载。该构建器还提供add_handler_after/add_handler_before/add_handler_last三个扩展点并支持通过HeartbeatHandlerGroupBuilderCustomizer插件化定制链测试与扩展都围绕这套机制展开。DDL 流程DDL 由 src/meta-srv/src/service/procedure.rs 暴露是Leader-only的非 Leader 节点会返回 not leader。Leader 收到 DDL 请求后交给common-meta的DdlManager处理并经由common-procedure以可恢复过程的形式执行。这意味着 DDL 状态会被持久化到 KV 后端节点崩溃后可恢复继续执行。Region 迁移流程Region 迁移由 src/meta-srv/src/procedure/region_migration/manager.rs 以及region_migration/目录下的分步文件实现。从目录结构看迁移被拆分为多个步骤migration_start.rs/migration_end.rs/migration_abort.rs— 迁移的启停与中止downgrade_leader_region.rs/flush_leader_region.rs/close_downgraded_region.rs— 旧 Leader Region 降级与刷盘关闭open_candidate_region.rs/upgrade_candidate_region.rs— 候选 Region 打开与升级update_metadata.rs及其子步骤upgrade_candidate_region、downgrade_leader_region、rollback_downgraded_region— 元数据更新与回滚。迁移可以由故障转移触发也可以通过显式命令发起其状态机定义与执行步骤可进一步参考 src/meta-srv/src/procedure/region_migration.rs。Leader 选举流程选举能力来自common-meta的 election 抽象etcd 后端对应EtcdElectionmeta-srv侧的状态迁移集中在 src/meta-srv/src/state.rs。当选时become_leader()触发 Leader 缓存初始化失选时become_follower()回退状态并重置 Leader 缓存从而保证新的 Leader 从 KV 后端重建内存视图。MetasrvOptions 配置详解配置结构体MetasrvOptions定义在 src/meta-srv/src/metasrv.rs完整示例见 config/metasrv.example.toml。下面按主题分组解读核心配置项。元数据后端backend / store_addrsbackend元数据存储实现对应BackendImpl枚举src/meta-srv/src/metasrv.rs取值包括etcd_store默认、memory_store测试用、postgres_store与mysql_store需编译对应 featurepg_kvbackend/mysql_kvbackendstore_addrs后端地址列表。etcd 为host:port列表PostgreSQL 为 libpq 连接串或 URIMySQL 为连接 URLstore_key_prefix非空时所有 KV key 加此前缀用于多个 meta-srv 集群共享同一存储max_txn_ops单事务最大操作数默认 128应小于 etcd 的--max-txn-opsbackend_client后端客户端保活与连接超时keep_alive_timeout3s、keep_alive_interval10s、connect_timeout3sbackend_tlsKV 后端的 TLS 配置支持disable/prefer/require/verify_ca/verify_full五种模式。心跳与故障转移heartbeat / failoverheartbeat_interval基础心跳间隔用于推导分布式时间常量例如 Region 租约时长约为heartbeat_interval * 3 1s。Frontend 的心跳间隔是基础间隔的 6 倍Datanode/Flownode 为 1 倍心跳间隔在握手阶段由 MetaSrv 协商下发节点本地配置不会覆盖它enable_region_failover是否启用 Region 故障转移仅在使用 Remote WAL 共享存储如 S3的集群模式下可用region_failure_detector_initialization_delayRegion 故障检测启动前的延迟默认 10 分钟避免 Datanode 尚未全部就绪时误触发 failover对未使用 GreptimeDB Operator 且未开启维护模式的部署尤为重要allow_region_failover_on_local_wal是否允许本地 WAL 场景下的 Region failover官方不建议开启可能造成数据丢失node_max_idle_time节点信息从 MetaSrv 内存移除前的最大空闲时间默认 24h。状态机与过程state / procedure[procedure]过程执行配置。max_retry_times12最大重试次数、retry_delay500ms初始重试延迟指数递增、max_metadata_value_size1500KiBetcd 单请求上限 1.5 MiB 减去 36KiB key 保留空间、max_running_procedures128并发过程上限超出即拒绝。故障检测failure_detectorMetaSrv 使用Phi Accrual Failure Detector算法检测 Datanode 故障threshold默认 8.0判定 Peer 故障的 φ 阈值越小反应越快但误报越多min_std_deviation默认 100ms心跳间隔的最小标准差防止间隔几乎不变时 φ 爆炸acceptable_heartbeat_pause默认 10000ms心跳间可接受的暂停时长为学习到的平均间隔追加额外宽限期吸收网络抖动与 GC 暂停。Region 放置selectorselector决定 Region 放置在哪个 Peer 上支持三种策略round_robin默认轮询分配lease_based基于租约load_based基于负载。对应实现见 src/meta-srv/src/selector/round_robin.rs、load_based.rs、lease_based.rs以及weight_compute.rs/weighted_choose.rs提供的加权计算。修改 selector 时需注意与RegionStatAwareSelector消费的统计字段保持一致见下文修改关联。统计持久化与 GCstats / gc[stats_persistence]ttl默认0s关闭持久化大于 0 时开启建议小值如3hinterval默认10m低于10m会被强制覆盖为10m[gc]enablefalse默认关闭且必须与 Datanode 的mito.gc.enable保持一致gc_cooldown_period5m为同一 Region 两次 GC 之间的冷却期。事件记录与遥测event_recorder / telemetry[event_recorder]事件表 TTL 默认90devent_types为空数组时禁用记录省略时记录全部当前与未来事件类型如region_migration、create_table、repartition、wal_prune、batch_gc等enable_telemetry默认开启 GreptimeDB 遥测。gRPC / HTTP 监听[grpc]bind_addr默认127.0.0.1:3002、server_addr向 Frontend/Datanode 通告的地址留空则自动取主机第一网卡 IP 加同端口、runtime_size、max_recv/send_message_size、HTTP/2 keep-alive 参数[http]addr默认127.0.0.1:4000、timeout、body_limit默认64MB。WAL 配置walMetaSrv 在 Kafka 作为远端 WAL 时需要同步配置[wal]providerraft_engine默认或kafkaKafka 相关broker_endpoints、auto_create_topics、num_topics64、topic_name_prefix、replication_factor、selector_type、SASL/TLSauto_prune_interval30m自动清理远端 WAL 的间隔0s关闭auto_prune_logical_delete用于不支持 DeleteRecords 的 Kafka 部署flush_trigger_size512MB/checkpoint_trigger_size128MB基于(latest_entry_id - flushed_entry_id) * avg_record_size估算的刷盘/检查点触发阈值0表示由系统自行决定。公开接口客户端与 Admin APIAGENTS.md 明确指出对外接口分两侧客户端侧统一使用meta-clientcrate 的MetaClient封装了对 MetaSrv 各 gRPC 服务的调用服务端侧入口是 src/meta-srv/src/service/ 下的 gRPC 服务heartbeat、procedure、cluster、store以及 src/meta-srv/src/service/admin/ 下的 HTTP admin API。从 admin 目录可看到一组实用的运维接口health健康检查、leader查看当前 Leader、procedure过程管理、maintenance维护模式、recovery恢复、node_lease节点租约、sequencer序列号、heartbeat心跳调试等。修改代码时的联动关系AGENTS.md 的When you change X, also touch Y部分给出了高度可操作的联动清单这既是维护契约也是理解模块耦合的捷径心跳间隔 / 租约时间常量定义在common-meta的distributed_time_constants源码中可见BASE_HEARTBEAT_INTERVAL、frontend_heartbeat_interval等引用见 src/meta-srv/src/metasrv.rs修改它会同时影响handler/region_lease_handler.rs的租约续期与region/supervisor.rs的故障判定。过程Procedure状态必须持久化在 KV 后端且execute()必须幂等才能保证崩溃恢复正确这与 .agents/architecture-invariants.md 的持久化格式兼容性约束一致。缓存失效新增元数据类型时需要在cache_invalidator.rs与心跳发布处理器PublishHeartbeatHandler中同步补充失效逻辑。Selector 统计字段selector/的实现必须与其消费的统计字段保持同步否则 Region 放置会读到错误数据。测试方法AGENTS.md 给出了标准的测试命令# 运行 meta-srv 的全部测试 cargo nextest run -p meta-srv # 使用 mock 选举 / KV 后端更快的单元测试 cargo nextest run -p meta-srv --features mockmockfeature 在 src/meta-srv/Cargo.toml 中声明可避免依赖真实 etcd。测试基础设施还包括三个辅助文件src/meta-srv/src/mocks.rs — 各类 mock 组件src/meta-srv/src/test_util.rs — 通用测试工具src/meta-srv/src/procedure/test_util.rs — 过程测试工具。此外handler.rs的测试模块中大量使用HeartbeatHandlerGroupBuilder::new(...).add_default_handlers()组装真实处理器链并通过add_handler_after/add_handler_before注入自定义处理器验证链的顺序与扩展点行为src/meta-srv/src/handler.rs。常见陷阱GotchasAGENTS.md 总结了三个最容易踩坑的点也是 review 与排障的检查清单写操作必须 Leader-only绝大多数变更操作只允许 Leader 执行handler/与service/procedure.rs中都有对应的 Leader 检查非 Leader 节点统一返回 not leader。心跳会话中若监听到 Leader 下台也会主动断开见 src/meta-srv/src/service/heartbeat.rs。内存状态不可持久Leader 变更后需要保留的任何状态都必须写入 KV 后端Leader 使用LeaderCachedKvBackend该缓存会在 Leader 变更时重置。租约时序必须协调Region 租约续期节奏与 supervisor 的检查间隔必须协调否则同一个 Region 可能同时出现在两个 Datanode 上双活脑裂。维护契约何时更新 AGENTS.mdAGENTS.md 本身也是一份需要随代码演进的活文档其维护契约要求新增过程procedure、修改心跳处理器链、变更 Leader-only 边界、或调整 metasrv 与 common-meta 的分工时必须同步更新本文件。对贡献者而言遵循该契约可以确保这份导航文档始终与实际代码结构一致这也是本仓库将 crate 级 AGENTS.md 作为协作规范的一部分其余仓库级规范见 .agents/README.md 与 .agents/architecture-invariants.md。小结meta-srv是 GreptimeDB 分布式模式的控制面核心其设计呈现出清晰的分层 状态机 过程化特征元数据模型下沉到common-meta服务与状态机在meta-srv分布式操作全部以可恢复过程执行心跳链则通过可定制的处理器组完成拓扑感知与指令下发。理解模块地图、四条核心流程、MetasrvOptions配置语义以及联动修改清单是深入参与 meta-srv 开发与运维的第一步配合cargo nextest run -p meta-srv与 mock feature你可以快速验证改动而不必依赖真实集群。【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GreptimeDB 分布式元数据服务 meta-srv 架构深度解析：心跳、选举、分布式过程与配置实战
GreptimeDB 分布式元数据服务 meta-srv 架构深度解析心跳、选举、分布式过程与配置实战【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedbGreptimeDB 采用存算分离的分布式架构而meta-srv正是这套集群的元数据大脑它持久化集群/表/Region 元数据、负责 Leader 选举、驱动心跳循环追踪集群拓扑并编排 DDL、Region 迁移、Repartition 等分布式过程。本文以 src/meta-srv/AGENTS.md 为核心脉络结合meta-srvcrate 源码与 config/metasrv.example.toml 真实配置系统讲解其模块划分、核心流程、配置项语义、公开接口与测试方法帮助你理解并维护 GreptimeDB 的元数据服务层。meta-srv 在整个项目中的定位在分布式模式下GreptimeDB 由 Frontend、Datanode、Flownode 与 MetaSrv 共同组成。meta-srv承担元数据与协调职能具体包括持久化集群/表/Region 元数据所有元数据以 KV 形式写入后端存储默认 etcd跨节点共享Leader 选举在多个 MetaSrv 副本之间选出唯一 Leader保证写操作一致性心跳循环与集群拓扑追踪通过 Frontend/Datanode/Flownode 上报的心跳维护节点存活状态与集群拓扑分布式过程编排DDL建表/删表等、Region 迁移、Repartition 等操作以可恢复的过程Procedure形式执行。从 crate 依赖来看数据模型、KV 后端抽象、选举、Key 编码与 DDL 管理器都实现在common-metacrate 中meta-srv在其之上实现服务端、状态机与控制逻辑。分层遵循仓库级架构约束见 .agents/architecture-invariants.md 中common-* 不能反向依赖 storage engine、frontend、datanode、meta-srv的约定meta-srv通过common-meta、common-procedure等基础 crate 协作而不是重复实现元数据模型。模块地图meta-srv 源码导航meta-srv的源码全部位于 src/meta-srv/srcAGENTS.md 给出了清晰的模块导航表。下面按模块逐一说明其职责与关键文件模块路径职责bootstrapsrc/meta-srv/src/bootstrap.rs组装 KV 后端、选举、gRPC 服务与过程管理器完成进程启动metasrvsrc/meta-srv/src/metasrv.rs、src/meta-srv/src/metasrv/builder.rsMetasrv结构体、MetasrvOptions配置、MetasrvBuilder构建器与启动逻辑statesrc/meta-srv/src/state.rsLeader/Follower 状态机与状态迁移handlersrc/meta-srv/src/handler/心跳处理器链HeartbeatHandlerLeader 检查、Region 租约、统计、信箱servicesrc/meta-srv/src/service/gRPC 服务heartbeat、procedure、cluster、store与 HTTP admin 接口proceduresrc/meta-srv/src/procedure/分布式过程region_migration/、repartition.rs、wal_prune/regionsrc/meta-srv/src/region/Region 监督器、租约维护、故障转移触发discoverysrc/meta-srv/src/discovery/节点发现与基于租约的节点信息pubsubsrc/meta-srv/src/pubsub/心跳主题的发布/订阅支持gcsrc/meta-srv/src/gc/元数据驱动的垃圾回收过程与调度selectorsrc/meta-srv/src/selector/Region 放置策略round-robin / load-based / lease-basedpeersrc/meta-srv/src/peer.rs通过 selector 分配 Peerclustersrc/meta-srv/src/cluster.rsMetaPeerClient带 Leader 回退的内部 RPCcache_invalidatorsrc/meta-srv/src/cache_invalidator.rs向 Frontend/Datanode 推送缓存失效通知keysrc/meta-srv/src/key/MetaSrv 侧的 KV Key 编码bootstrap启动装配与 gRPC 路由bootstrap.rs中的MetasrvInstance::start()是进程启动的核心入口先启动 HTTP 服务再通过router()函数装配 gRPC 服务。从 src/meta-srv/src/bootstrap.rs 可以看出gRPC 路由依次注册了五个服务且全部开启 Gzip/Zstd 压缩与消息大小限制HeartbeatServer心跳服务接收 Frontend/Datanode/Flownode 的心跳流StoreServer元数据 KV 读写服务ClusterServer集群管理服务ProcedureServiceServer过程执行服务ConfigServer配置下发服务admin::make_admin_service兼容旧版的 admin 服务。后端选择逻辑见metasrv_builder()src/meta-srv/src/bootstrap.rs根据opts.backend决定使用MemoryKvBackend测试用、EtcdStore默认并同时构造EtcdElection或 PostgreSQL/MySQL需要对应 feature。stateLeader/Follower 状态机src/meta-srv/src/state.rs 中有一段 ASCII 状态图完整描述了状态迁移路径------------------------------ | | v | -------------------v-------------------- | | LeaderState{enable_leader_cache:false} | | --------------------------------------- | | | ---------v--------- | | Init Leader Cache | | ------------------ | | | -------------------v------------------- | | LeaderState{enable_leader_cache:true} | | -------------------------------------- | | | -------v------- | | FollowerState | | -------------- | | | ------------------------------关键语义新 Leader 上任时先进入enable_leader_cache: false状态此时禁用 Leader 缓存完成缓存初始化后切换为enable_leader_cache: true一旦发生 Leader 变更则回退为FollowerState。become_leader()与become_follower()两个函数src/meta-srv/src/state.rs正是上述迁移的具体实现。这正是 AGENTS.md 中Leader 使用在 Leader 变更时重置的缓存 KV 后端LeaderCachedKvBackend这一注意事项的状态机体现。核心流程四条主线AGENTS.md 归纳了四条核心流程下面结合源码逐一展开。心跳流程Heartbeat心跳是集群拓扑感知的基础。service/heartbeat.rs中的HeartbeatSession维护一条 gRPC 双向流收到首个心跳请求后校验RequestHeader并向HeartbeatHandlerGroup注册 pushersrc/meta-srv/src/service/heartbeat.rs循环select两条事件流上新的心跳消息、或 Leader 下台事件wait_leader_step_down。一旦通过选举订阅收到LeaderChangeMessage::StepDown立即向客户端返回 not leader 错误并终止会话src/meta-srv/src/service/heartbeat.rs响应中携带信箱mailbox消息用于下发 DDL 结果、缓存失效等指令。每个心跳请求会顺序穿过handler/下的处理器链。从 src/meta-srv/src/handler.rs 的add_default_handlers()可以看到默认链的完整组成顺序即执行顺序ResponseHeaderHandler— 写入响应头DatanodeKeepLeaseHandler/FlownodeKeepLeaseHandler— 续租节点租约CheckLeaderHandler— 仅 Leader 处理非 Leader 返回 not leaderOnLeaderStartHandler— Leader 上任初始化ExtractStatHandler— 提取节点统计CollectDatanodeClusterInfoHandler/CollectFrontendClusterInfoHandler/CollectFlownodeClusterInfoHandler— 采集各角色集群信息MailboxHandler— 处理信箱消息RegionLeaseHandler— Region 租约续期条件挂载FilterInactiveRegionStatsHandler— 过滤非活跃 Region 统计RegionFailureHandler— Region 故障处理开启 failover 时挂载PublishHeartbeatHandler— 向 pubsub 发布心跳开启时挂载CollectLeaderRegionHandler— 采集 Leader Region 信息CollectTopicStatsHandler— 采集 WAL 主题统计PersistStatsHandler— 持久化统计开启时挂载CollectStatsHandler— 汇总统计基于flush_stats_factor触发刷写RemapFlowPeerHandler— 流FlowPeer 重映射FlowStateHandler— 流状态处理条件挂载。该构建器还提供add_handler_after/add_handler_before/add_handler_last三个扩展点并支持通过HeartbeatHandlerGroupBuilderCustomizer插件化定制链测试与扩展都围绕这套机制展开。DDL 流程DDL 由 src/meta-srv/src/service/procedure.rs 暴露是Leader-only的非 Leader 节点会返回 not leader。Leader 收到 DDL 请求后交给common-meta的DdlManager处理并经由common-procedure以可恢复过程的形式执行。这意味着 DDL 状态会被持久化到 KV 后端节点崩溃后可恢复继续执行。Region 迁移流程Region 迁移由 src/meta-srv/src/procedure/region_migration/manager.rs 以及region_migration/目录下的分步文件实现。从目录结构看迁移被拆分为多个步骤migration_start.rs/migration_end.rs/migration_abort.rs— 迁移的启停与中止downgrade_leader_region.rs/flush_leader_region.rs/close_downgraded_region.rs— 旧 Leader Region 降级与刷盘关闭open_candidate_region.rs/upgrade_candidate_region.rs— 候选 Region 打开与升级update_metadata.rs及其子步骤upgrade_candidate_region、downgrade_leader_region、rollback_downgraded_region— 元数据更新与回滚。迁移可以由故障转移触发也可以通过显式命令发起其状态机定义与执行步骤可进一步参考 src/meta-srv/src/procedure/region_migration.rs。Leader 选举流程选举能力来自common-meta的 election 抽象etcd 后端对应EtcdElectionmeta-srv侧的状态迁移集中在 src/meta-srv/src/state.rs。当选时become_leader()触发 Leader 缓存初始化失选时become_follower()回退状态并重置 Leader 缓存从而保证新的 Leader 从 KV 后端重建内存视图。MetasrvOptions 配置详解配置结构体MetasrvOptions定义在 src/meta-srv/src/metasrv.rs完整示例见 config/metasrv.example.toml。下面按主题分组解读核心配置项。元数据后端backend / store_addrsbackend元数据存储实现对应BackendImpl枚举src/meta-srv/src/metasrv.rs取值包括etcd_store默认、memory_store测试用、postgres_store与mysql_store需编译对应 featurepg_kvbackend/mysql_kvbackendstore_addrs后端地址列表。etcd 为host:port列表PostgreSQL 为 libpq 连接串或 URIMySQL 为连接 URLstore_key_prefix非空时所有 KV key 加此前缀用于多个 meta-srv 集群共享同一存储max_txn_ops单事务最大操作数默认 128应小于 etcd 的--max-txn-opsbackend_client后端客户端保活与连接超时keep_alive_timeout3s、keep_alive_interval10s、connect_timeout3sbackend_tlsKV 后端的 TLS 配置支持disable/prefer/require/verify_ca/verify_full五种模式。心跳与故障转移heartbeat / failoverheartbeat_interval基础心跳间隔用于推导分布式时间常量例如 Region 租约时长约为heartbeat_interval * 3 1s。Frontend 的心跳间隔是基础间隔的 6 倍Datanode/Flownode 为 1 倍心跳间隔在握手阶段由 MetaSrv 协商下发节点本地配置不会覆盖它enable_region_failover是否启用 Region 故障转移仅在使用 Remote WAL 共享存储如 S3的集群模式下可用region_failure_detector_initialization_delayRegion 故障检测启动前的延迟默认 10 分钟避免 Datanode 尚未全部就绪时误触发 failover对未使用 GreptimeDB Operator 且未开启维护模式的部署尤为重要allow_region_failover_on_local_wal是否允许本地 WAL 场景下的 Region failover官方不建议开启可能造成数据丢失node_max_idle_time节点信息从 MetaSrv 内存移除前的最大空闲时间默认 24h。状态机与过程state / procedure[procedure]过程执行配置。max_retry_times12最大重试次数、retry_delay500ms初始重试延迟指数递增、max_metadata_value_size1500KiBetcd 单请求上限 1.5 MiB 减去 36KiB key 保留空间、max_running_procedures128并发过程上限超出即拒绝。故障检测failure_detectorMetaSrv 使用Phi Accrual Failure Detector算法检测 Datanode 故障threshold默认 8.0判定 Peer 故障的 φ 阈值越小反应越快但误报越多min_std_deviation默认 100ms心跳间隔的最小标准差防止间隔几乎不变时 φ 爆炸acceptable_heartbeat_pause默认 10000ms心跳间可接受的暂停时长为学习到的平均间隔追加额外宽限期吸收网络抖动与 GC 暂停。Region 放置selectorselector决定 Region 放置在哪个 Peer 上支持三种策略round_robin默认轮询分配lease_based基于租约load_based基于负载。对应实现见 src/meta-srv/src/selector/round_robin.rs、load_based.rs、lease_based.rs以及weight_compute.rs/weighted_choose.rs提供的加权计算。修改 selector 时需注意与RegionStatAwareSelector消费的统计字段保持一致见下文修改关联。统计持久化与 GCstats / gc[stats_persistence]ttl默认0s关闭持久化大于 0 时开启建议小值如3hinterval默认10m低于10m会被强制覆盖为10m[gc]enablefalse默认关闭且必须与 Datanode 的mito.gc.enable保持一致gc_cooldown_period5m为同一 Region 两次 GC 之间的冷却期。事件记录与遥测event_recorder / telemetry[event_recorder]事件表 TTL 默认90devent_types为空数组时禁用记录省略时记录全部当前与未来事件类型如region_migration、create_table、repartition、wal_prune、batch_gc等enable_telemetry默认开启 GreptimeDB 遥测。gRPC / HTTP 监听[grpc]bind_addr默认127.0.0.1:3002、server_addr向 Frontend/Datanode 通告的地址留空则自动取主机第一网卡 IP 加同端口、runtime_size、max_recv/send_message_size、HTTP/2 keep-alive 参数[http]addr默认127.0.0.1:4000、timeout、body_limit默认64MB。WAL 配置walMetaSrv 在 Kafka 作为远端 WAL 时需要同步配置[wal]providerraft_engine默认或kafkaKafka 相关broker_endpoints、auto_create_topics、num_topics64、topic_name_prefix、replication_factor、selector_type、SASL/TLSauto_prune_interval30m自动清理远端 WAL 的间隔0s关闭auto_prune_logical_delete用于不支持 DeleteRecords 的 Kafka 部署flush_trigger_size512MB/checkpoint_trigger_size128MB基于(latest_entry_id - flushed_entry_id) * avg_record_size估算的刷盘/检查点触发阈值0表示由系统自行决定。公开接口客户端与 Admin APIAGENTS.md 明确指出对外接口分两侧客户端侧统一使用meta-clientcrate 的MetaClient封装了对 MetaSrv 各 gRPC 服务的调用服务端侧入口是 src/meta-srv/src/service/ 下的 gRPC 服务heartbeat、procedure、cluster、store以及 src/meta-srv/src/service/admin/ 下的 HTTP admin API。从 admin 目录可看到一组实用的运维接口health健康检查、leader查看当前 Leader、procedure过程管理、maintenance维护模式、recovery恢复、node_lease节点租约、sequencer序列号、heartbeat心跳调试等。修改代码时的联动关系AGENTS.md 的When you change X, also touch Y部分给出了高度可操作的联动清单这既是维护契约也是理解模块耦合的捷径心跳间隔 / 租约时间常量定义在common-meta的distributed_time_constants源码中可见BASE_HEARTBEAT_INTERVAL、frontend_heartbeat_interval等引用见 src/meta-srv/src/metasrv.rs修改它会同时影响handler/region_lease_handler.rs的租约续期与region/supervisor.rs的故障判定。过程Procedure状态必须持久化在 KV 后端且execute()必须幂等才能保证崩溃恢复正确这与 .agents/architecture-invariants.md 的持久化格式兼容性约束一致。缓存失效新增元数据类型时需要在cache_invalidator.rs与心跳发布处理器PublishHeartbeatHandler中同步补充失效逻辑。Selector 统计字段selector/的实现必须与其消费的统计字段保持同步否则 Region 放置会读到错误数据。测试方法AGENTS.md 给出了标准的测试命令# 运行 meta-srv 的全部测试 cargo nextest run -p meta-srv # 使用 mock 选举 / KV 后端更快的单元测试 cargo nextest run -p meta-srv --features mockmockfeature 在 src/meta-srv/Cargo.toml 中声明可避免依赖真实 etcd。测试基础设施还包括三个辅助文件src/meta-srv/src/mocks.rs — 各类 mock 组件src/meta-srv/src/test_util.rs — 通用测试工具src/meta-srv/src/procedure/test_util.rs — 过程测试工具。此外handler.rs的测试模块中大量使用HeartbeatHandlerGroupBuilder::new(...).add_default_handlers()组装真实处理器链并通过add_handler_after/add_handler_before注入自定义处理器验证链的顺序与扩展点行为src/meta-srv/src/handler.rs。常见陷阱GotchasAGENTS.md 总结了三个最容易踩坑的点也是 review 与排障的检查清单写操作必须 Leader-only绝大多数变更操作只允许 Leader 执行handler/与service/procedure.rs中都有对应的 Leader 检查非 Leader 节点统一返回 not leader。心跳会话中若监听到 Leader 下台也会主动断开见 src/meta-srv/src/service/heartbeat.rs。内存状态不可持久Leader 变更后需要保留的任何状态都必须写入 KV 后端Leader 使用LeaderCachedKvBackend该缓存会在 Leader 变更时重置。租约时序必须协调Region 租约续期节奏与 supervisor 的检查间隔必须协调否则同一个 Region 可能同时出现在两个 Datanode 上双活脑裂。维护契约何时更新 AGENTS.mdAGENTS.md 本身也是一份需要随代码演进的活文档其维护契约要求新增过程procedure、修改心跳处理器链、变更 Leader-only 边界、或调整 metasrv 与 common-meta 的分工时必须同步更新本文件。对贡献者而言遵循该契约可以确保这份导航文档始终与实际代码结构一致这也是本仓库将 crate 级 AGENTS.md 作为协作规范的一部分其余仓库级规范见 .agents/README.md 与 .agents/architecture-invariants.md。小结meta-srv是 GreptimeDB 分布式模式的控制面核心其设计呈现出清晰的分层 状态机 过程化特征元数据模型下沉到common-meta服务与状态机在meta-srv分布式操作全部以可恢复过程执行心跳链则通过可定制的处理器组完成拓扑感知与指令下发。理解模块地图、四条核心流程、MetasrvOptions配置语义以及联动修改清单是深入参与 meta-srv 开发与运维的第一步配合cargo nextest run -p meta-srv与 mock feature你可以快速验证改动而不必依赖真实集群。【免费下载链接】greptimedbThe open-source observability database. One columnar engine for metrics, logs, and traces, on object storage.项目地址: https://gitcode.com/GitHub_Trending/gr/greptimedb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考