TiKV 维护指南Maintenance Guides全解析维护者地图、Review 检查清单与源码锚点【免费下载链接】tikvDistributed transactional key-value database, originally created to complement TiDB项目地址: https://gitcode.com/GitHub_Trending/ti/tikvTiKV 是一个分布式事务型键值数据库本仓库既是其全部源码所在也沉淀了一套面向维护者maintainer与评审者reviewer的「维护指南Maintenance Guides」体系。本文以 doc/maintenance-guides/README.md 为骨架结合仓库内repo-overview.md与 13 份子系统指南完整解读这套维护者地图的组织方式、统一章节契约、系统地图、跨组件评审清单并给出每个子系统的源码入口与必须优先阅读的文件帮助读者在最短时间内回答四个问题这个行为归哪个子系统管真正的入口文件在哪里哪些不变量容易被破坏哪些测试与指标应当随变更一起移动维护指南的定位为维护者而写的索引而非用户手册doc/maintenance-guides/README.md开宗明义地指出这个目录是面向维护方向的仓库索引maintainership-oriented index不是用户手册。它服务的对象是评审者和开发者目标是让人能快速回答四个问题哪个子系统拥有这个行为Which subsystem owns this behavior哪些文件是真正的入口点Which files are the real entry points哪些不变量容易被破坏Which invariants are easy to break哪些测试和指标应该随变更一起移动Which tests and metrics should move with the change因此这套文档的写作粒度是「维护边界maintenance boundary」而不是「用户功能user feature」它聚焦于代码归属、启动顺序、数据契约、运行信号与阅读地图而非部署或 SQL 语义。理解这一点是正确使用整套指南的前提。维护者契约Maintainer ContractREADME 将这套文档定义为仓库「维护面maintenance surface」的一部分并给出了明确的义务条款开发者在进行非平凡变更前应当先阅读对应子系统的指南评审者在评审前也应如此这些指南是「实现与评审的辅助文档」而不是可选的「事后补充」如果一个变更修改了归属边界、启动顺序、数据契约、不变量、运维信号或推荐阅读地图那么必须在该变更中同步更新本目录中对应的指南一个使指南失效却不更新指南的代码变更应被视为不完整的维护变更。这条契约的本质是把文档维护义务与代码变更绑定在一起文档不是摆设而是与代码同生命周期、需要同步演进的评审依据。统一结构子系统指南的标准章节契约Standard Section Contract为了让 13 份子系统指南保持一致的阅读体验README 规定了每份指南都必须覆盖的10 个领域Purpose and scope目的与范围Architectural views架构视图Process lifecycle and startup sequencing进程生命周期与启动顺序Data model and metadata contracts数据模型与元数据契约Observability and operational signals可观测性与运维信号Change management guidance变更管理指引Reading map and companion docs阅读地图与配套文档Glossary术语表Must-read file order必读文件顺序Change-impact matrix变更影响矩阵README 同时指出深度随子系统规模而变小型胶水 crate 可以把某些章节写短但章节应当保持存在。以实际指南为例doc/maintenance-guides/components/batch-system.md 覆盖了batch-systemraftstore 底层的通用 FSM 执行框架的 mailbox 路由、轮询批处理、重调度与池级指标并给出构造路径batch.rs::create_system与 shutdown 使用的FsmTypes::Empty哨兵逻辑doc/maintenance-guides/components/hybrid_engine.md 则强调这是一个「薄组合层」磁盘 KV 引擎仍具权威性region cache 引擎是机会式的混合快照按 CF 与快照可用性选择后端且cache 可见性必须以磁盘快照的 sequence number 为权威来源见 snapshot.rs。如何阅读这套指南How To Use This SetREADME 给出了推荐的阅读流程先读 doc/maintenance-guides/repo-overview.md 理解分层边界打开你正在改动的子系统对应的指南优先使用「必读文件顺序」「变更影响矩阵」和「评审检查清单」三个章节当变更为非平凡级别时把指南当作开发或评审的必需上下文记住一条总原则把每份指南当作地图而不是完整规范真正的真相仍然在代码里Treat every guide as a map, not a complete specification. The source of truth is still the code。系统地图System Map仓库级归属速查README 用一张「系统地图」标定了核心子系统与代码路径的对应关系这是全文最实用的归属速查表现完整列出路径已转换为仓库根目录相对路径功能域代码位置进程启动与组件装配Startup and process wiringcomponents/server运行时 gRPC、Raft transport、status server、GC、debug 服务src/serverRaftKv2桥接与基于 tablet 的副本栈src/server/raftkv2 components/raftstore-v2事务 KV、MVCC、raw KV、调度、锁等待src/storage经典 TiDB coprocessor DAG / analyze / checksum 路径src/coprocessor插件化 coprocessor 框架src/coprocessor_v2经典 raft-kv 副本状态机、路由、快照、split/heartbeat workercomponents/raftstoreEngineType::RaftKv2的 tablet 副本状态机components/raftstore-v2raftstore 重度依赖的通用 FSM 批处理框架components/batch-system资源组、公平性、准入控制、配额调整components/resource_control磁盘 region-cache 引擎胶水层components/hybrid_engineregion cache 引擎与后台生命周期components/in_memory_engineserver / status server 使用的小型服务控制 shimcomponents/service注意这张表同时覆盖了两条复制路径经典raftstore路径与RaftKv2/raftstore-v2的 tablet 路径。评审时先判断改动落在哪条路径再决定是否需要对另一条路径做平行审计。指南索引Guide IndexREADME 维护了一份完整的指南清单共 13 份子系统指南加 1 份仓库总览仓库级Repository Overviewcomponents/下raftstore、raftstore-v2、resource_control、hybrid_engine、in_memory_engine、batch-system、server、servicesrc/下coprocessor、coprocessor_v2、server、storage跨组件评审检查清单Cross-Cutting Review Checklist这是 README 中面向「任何非平凡变更」的通用审查清单无论改动落在哪个子系统都应逐项核对性能关键路径检查变更是否触及#[PerformanceCriticalPath]标注的文件或请求热路径仓库根目录的 PERFORMANCE_CRITICAL_PATH.md 是配套说明边界层确认变更是否位于边界层——src/server/service/kv.rs、src/storage/mod.rs、src/storage/txn/scheduler.rs、components/raftstore/src/store/peer.rs、components/batch-system/src/batch.rs线程/worker 归属确认 read pools、background workers、Yatp 任务、raft/apply pollers、status server 的所有权region 级假设region epoch、bounds、leader 状态、快照生命周期、safe point、read tsresource-control 钩子请求元数据、配额限流器、公平调度、准入控制标签可观测性metrics、tracing、慢日志、内存记账、health/status 端点动态配置行为config 结构体、config manager、运行时副作用、兼容性失败语义超时、取消、重试、未决结果undetermined result、背压、降级服务模式测试随行为移动内联单元测试、failpoints、components/test_raftstore、components/test_storage、components/test_coprocessor。其中第 3、4、6、8 项直接对应 TiKV 这类分布式存储最容易出问题的领域跨线程所有权、region epoch 与快照生命周期、热路径上的指标开销、以及回调完成语义。当前覆盖范围Current Scope与已知盲区README 明确列出了当前指南集的覆盖范围与尚未覆盖的子系统评审时应特别注意后者属于「已知盲区」已覆盖13 1 份repo-overview.md、components/raftstore.md、components/raftstore-v2.md、components/resource_control.md、components/hybrid_engine.md、components/in_memory_engine.md、components/batch-system.md、components/server.md、components/service.md、src/coprocessor.md、src/coprocessor_v2.md、src/server.md、src/storage.md。指南集在维护者地图粒度上同时覆盖了经典raftstore路径与RaftKv2/raftstore-v2路径聚焦维护与评审而非外部部署或 SQL 语义。尚无独立子系统指南、仅在仓库总览中涉及跨组件推理时需要额外留意components/cdc变更数据捕获components/backup与components/backup-stream备份与日志备份components/engine_rocksRocksDB 引擎components/pd_clientPD 客户端components/sst_importer与src/importSST 导入也就是说若变更涉及 CDC、备份、导入/恢复等面README 建议结合受影响存储/raftstore 契约与 doc/maintenance-guides/repo-overview.md 中的跨组件推理共同评估。仓库总览的纵深补充从地图到源码锚点doc/maintenance-guides/repo-overview.md 是整套指南的顶层维护地图它把 README 中的系统地图进一步细化成可操作的知识以下几块对日常维护最具价值。进程生命周期与启动/关闭顺序启动顺序高层面为校验配置 → 初始化日志、文件系统状态、锁文件、预留磁盘空间与 panic 标记 → 初始化引擎 → 构建 workers、read pools、配额限流器、resource control 与 coprocessor/运行时服务 → 启动 raftstore 与 storage 桥接 → 启动 gRPC server、status server 等辅助服务 → 进入服务事件循环处理 pause/resume/shutdown。关闭顺序大致是启动顺序的逆序。总览特别强调启动与关闭顺序不仅是运维细节更是正确性问题——跨线程、跨 worker 的所有权 bug 往往在此暴露。对应的具体源码锚点均为仓库内真实路径进程设置与配置持久化components/server/src/common.rs、components/server/src/setup.rs经典启动全流程编排components/server/src/server.rs运行时 gRPC server 构造src/server/server.rs经典 raftstore 引导与 store 注册src/server/raft_server.rs经典写路径与 RaftKv2 写路径的平行审计总览给出了两条写路径的调用链并给出评审规则如果变更触及 storage 到复制层的桥接或回调语义必须显式审计两条路径。经典写路径classic write pathsrc/server/service/kv.rs 解析 RPC 并构造 storage 调用src/storage/mod.rs 与 src/storage/txn/scheduler.rs 将请求转为调度的命令src/server/raftkv/mod.rs 把 storage 写桥接到 raftstore 命令components/raftstore/src/router.rs 与components/raftstore/src/store/fsm/*将工作路由到 peer/store FSMcomponents/raftstore/src/store/peer.rs 及相关的 apply/write 路径驱动 raft 复制与持久化。RaftKv2写路径alternate write path的前两步与经典路径共用RPC 解析与 storage 调度第三步改为 src/server/raftkv2/mod.rs 桥接进 tablet 路径第四步由 components/raftstore-v2 负责 router、batch/FSM 执行与 tablet 侧持久化。前台/后台 IO 分离与确定性总览强调 TiKV 刻意将前台请求工作RPC 处理、scheduler 执行、raft pollers、本地读、coprocessor 执行与后台工作PD 心跳、GC、快照生成、compaction、cache 加载/驱逐、备份、CDC、指标刷新分离并给出两条硬规则避免在请求热路径或 FSM poller 上引入不必要的同步 IO即使后台卸载策略变化也必须保持回调顺序、消息顺序与快照语义的确定性。相关代码锚点前台读池 src/coprocessor/readpool_impl.rs 与 src/read_pool.rs文件系统 IO 类型与限速见file_system与 src/storage/config_manager.rsraftstore worker 分离见components/raftstore/src/store/worker/*。变更影响矩阵Change-Impact Matrix总览提供的矩阵把「改动类型」映射到「必须一起阅读的指南组合」评审时可直接查表启动/关闭/进程所有权改动同时读components/server、src/server、worker 生命周期与服务控制相关指南RPC 或请求边界改动同时读src/server、src/storage、src/coprocessor与 resource-control 指南事务、MVCC、回调或锁等待改动先读src/storage再看src/server与复制桥接指南副本、快照、split/merge、本地读或 apply 路径改动读components/raftstore、components/batch-system、src/server/raftkv相关代码并审计同样的推理是否适用于src/server/raftkv2/components/raftstore-v2cache 引擎或混合快照改动同时读components/in_memory_engine、components/hybrid_engine、src/coprocessor与复制 observer 装配公平性、准入或 RU 记账改动读components/resource_control、src/server/service/kv.rs、src/storage与components/batch-system导入、备份、恢复或 CDC 改动审计src/import、components/sst_importer、components/backup、components/backup-stream、components/cdc以及受影响的 storage 或 raftstore 契约。快速评审必读文件顺序Must-Read File Order当目标是评审或变更影响分析而非整体 onboarding时总览给出了更快的阅读顺序src/server/service/kv.rssrc/storage/mod.rssrc/storage/txn/scheduler.rssrc/server/raftkv/mod.rscomponents/raftstore/src/router.rscomponents/raftstore/src/store/peer.rscomponents/raftstore/src/store/fsm/apply.rssrc/coprocessor/endpoint.rscomponents/resource_control/src/lib.rscomponents/server/src/server.rs若变更主要针对EngineType::RaftKv2则提前换成平行锚点src/server/raftkv2/mod.rs、components/raftstore-v2/src/router/mod.rs、components/raftstore-v2/src/fsm/mod.rs、components/raftstore-v2/src/raft/mod.rs、components/raftstore-v2/src/operation/mod.rs。子系统指南速览几份高价值指南的要点components/raftstore风险最高的维护面之一doc/maintenance-guides/components/raftstore.md 明确指出这是 TiKV 中风险最高的维护面之一负责 raft/admin 请求路由、peer/store FSM 执行、本地读决策、快照生成与应用、split/merge 元数据转换、PD 心跳与 region/store 统计、raft 日志存储与 peer storage 状态。其「Start Here」入口包括 components/raftstore/src/lib.rs、router.rs、store/mod.rs、store/fsm/mod.rs、store/fsm/apply.rs、store/peer.rs、store/peer_storage.rs、store/msg.rs、store/worker/mod.rs。指南还给出一个典型的高风险契约示例基于负载的 split 候选可能比其观测到的 peer 身份活得更久执行时必须重新进入当前 peer FSM 并基于其当前Region 与 peer 构造 split 请求本地 follower 应拒绝该候选而不是转发给当前 leader。src/storage事务与存储层doc/maintenance-guides/src/storage.md 将src/storage定义为仓库最重要的维护面之一拥有StorageAPI、事务命令调度、MVCC、raw KV、latch 与锁等待、流控、存储相关动态配置。其高风险契约集中在default/lock/write 三个 CF 间的 MVCC 关系、ProcessResult与回调完成语义、TxnStatusCache与 max-ts 假设、以及 src/storage/config.rs 中的 raw KV API 版本与 TTL 规则该文件同时负责选择RaftKv与RaftKv2两种栈。components/resource_control资源治理doc/maintenance-guides/components/resource_control.md 描述其负责资源组的请求级公平性与资源隔离watch PD 元数据、维护组状态、用记账包装 future 与 channel、随时间调整限流器。其周期任务由lib.rs::start_periodic_tasks启动min-virtual-time 推进、PD watch 循环、配额调整、RU 上报PD watch/reload 循环在service.rs配额调整在worker.rs。components/in_memory_engine与components/hybrid_engine读加速栈doc/maintenance-guides/components/in_memory_engine.md 说明 region cache 引擎拥有缓存 region 生命周期、skiplist 存储、safe-point 感知快照、后台加载与 GC、内存驱动驱逐。关键契约在region_manager.rs与read.rs之间region_snapshot()在创建RegionCacheSnapshot前必须校验 region 身份、epoch、safe point 与活动状态read.rs要求有界迭代未提供上下界的调用会被拒绝。配置校验在config.rs::validate其中gc_run_interval边界、load_evict_interval最小值、capacity 与 block cache 的派生关系、阈值排序都不易在评审中发现。而 doc/maintenance-guides/components/hybrid_engine.md 补充了装配要点该 crate 在components/server/src/common.rs::build_hybrid_engine中组装随后必须在components/server/src/server.rs中注册HybridSnapshotObserver、LoadEvictionObserver、RegionCacheWriteBatchObserver——一个具备 cache 能力的HybridEngine若缺少配套 observer通常不是性能回退而是正确性 bug。把指南当作地图而不是规范整套维护指南的核心理念可以浓缩为一句话代码是唯一真相指南是帮助你快速找到真相的地图。因此读代码前先读地图README → repo-overview → 子系统指南评审时把「必读文件顺序」「变更影响矩阵」「跨组件检查清单」当作最小必需上下文凡是使指南失效的变更必须在同一变更里更新指南当指南与代码不一致时以代码为准并把修正指南本身当作维护工作的一部分。这套机制让 TiKV 这样规模庞大、子系统众多且存在双复制路径的仓库依然能在代码评审中保持对「归属、顺序、契约、信号」四类高风险问题的系统性覆盖。初次接触本仓库的开发者也可以按 repo-overview.md 给出的新维护者阅读顺序components/server/src/common.rs→components/server/src/server.rs→src/server/mod.rs→src/server/service/kv.rs→src/storage/mod.rs→src/storage/txn/scheduler.rs→src/server/raftkv/mod.rs→components/raftstore/src/router.rs→ ...逐步建立全局视图配合 README.md、PERFORMANCE_CRITICAL_PATH.md、CODE_COMMENT_STYLE.md、doc/http.md 与 doc/deploy.md 等配套文档即可从「看懂入口」走向「安全地修改与评审」。【免费下载链接】tikvDistributed transactional key-value database, originally created to complement TiDB项目地址: https://gitcode.com/GitHub_Trending/ti/tikv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考