Apache Pegasus 介绍与核心概念

介绍 Apache Pegasus 分布式键值存储：孵化状态与小米开源背景、架构三角色 meta/replica/collector、哈希分表与 RocksDB 存储、冷备份/负载均衡/ duplication 特性全景、与 Redis 协议兼容性及适用场景

Apache PegasusPegasusApacheNoSQL分布式KV2026/10/15

Apache Pegasus 介绍与核心概念

目标：说清 Apache Pegasus 是什么、解决什么问题、架构与核心概念如何组织、具备哪些功能特性、与 Redis 及同类产品的差异与适用场景。本文事实性描述以官网（pegasus.apache.org）overview 系列页面与官方文档目录为准并逐条标注来源；版本与运行行为在 Apache Pegasus 2.5.0（incubating）实测环境中验证通过（Ubuntu 22.04，onebox 模式 3 Meta + 3 Replica + Collector + 本地 ZooKeeper）。

一、环境信息

本文事实与结论基于以下资料与环境，引用处均标注来源。

项目值
软件全称Apache Pegasus（孵化中，incubating）
官网https://pegasus.apache.org
源码仓库https://github.com/apache/incubator-pegasus
当前最新稳定版2.5.0（官网《版本发布》页与 GitHub v2.5.0 tag 一致，2026-10 实测核实）
开发语言C++（背景页：写路径只依赖本地文件系统，不依赖 HDFS 等分布式文件系统）
存储引擎RocksDB（概览页）
一致性协议PacificA（概览页）
本文实测版本2.5.0（源码包 apache-pegasus-2.5.0-incubating-src.zip，sha512 校验一致）
实测系统Ubuntu 22.04（x86_64），onebox 单机集群模式
主要资料来源官网《概览》《系统架构》《数据模型》《体验 Onebox 集群》页，官方文档目录（下载/编译构建/客户端库/生态工具/用户接口/高效运维）

官网每个页面页脚均带有 ASF 孵化声明（Apache Pegasus is an effort undergoing incubation at The Apache Software Foundation, sponsored by the Apache Incubator），引用与转述本文均按 incubating 口径书写。

二、软件概述

2.1 定位与设计目标

Apache Pegasus 是一个分布式 Key-Value 存储系统。官网《概览》页给出四个设计目标，逐条摘录如下：

  • 高扩展性：通过哈希分片实现分布式横向扩展。
  • 强一致性：通过 PacificA 一致性协议保证。
  • 高性能：底层使用 RocksDB 作为存储引擎。
  • 简单易用：基于 Key-Value 的良好接口。

2.2 项目背景

官网《概览》页《背景》一节原文说明：Pegasus 项目的目标是弥补 Redis 与 HBase 之间的空白。Redis 作为纯内存存储提供了低延迟读写能力，但不具备强一致性；而与 HBase 不同，Pegasus 以 C++ 编写，同时其写路径应当只依赖于本地文件系统，不依赖其他分布式文件系统（如 HDFS），由此保证延迟稳定。除性能需求外，项目还要求存储系统能够支持多级别数据安全保障、快速跨数据中心迁移、自动负载均衡以及快速分片分裂等功能。

2.3 起源与孵化状态

  • 项目由小米发起并开源，官网《概览》页《社区分享》时间线最早可追溯到 2016 年（ArchSummit《从 Pegasus 看分布式系统的设计》，覃左言），小米内部有"上千个 Pegasus 集群"规模的实践分享（2021 年 meetup《我们是如何支撑起上千个 Pegasus 集群的》系列）。
  • 项目已捐赠给 Apache 软件基金会并进入孵化器：ApacheCon Asia 2021 的分享标题即为《Apache Pegasus (incubating): A distributed key-value storage system》；官方提案文档见 Apache Confluence 的 INCUBATOR/PegasusProposal 页面。截至本文撰写（基于 2026-10 实测抓取的官网页面），官网各页页脚仍标注 incubation 状态，具体转正时间线请以官网与 ASF 公告为准。

💡 说明：本文不编造未经验证的入孵时间与转正计划，孵化状态类表述一律以官网页脚与 ASF 官方渠道实时内容为准。

三、核心架构

3.1 四个组成部分

官网《系统架构》页明确：Pegasus 系统整体架构分为四个部分。各部分职责摘录如下：

组成部分职责（官网《系统架构》页）
Client Lib封装数据到存储服务器的映射规则，以及和存储服务器（Replica Server）的通信细节，提供一套简洁的 Key-Value 存取接口供用户使用
Replica Server负责数据存储，响应 Client Lib 的数据存取请求；以 replica 为管理单元提供服务，管理 commit log，并实现数据复制协议，提供数据一致性保证
Meta Server负责 Replica Server 的存活检测、数据分片（replica）管理、负载均衡等，通常采用一主多备的部署模式
Zookeeper负责对 Meta Server 进行选主，以实现 leader 节点的高可用，并存储系统的各种元数据

Meta Server 的功能细项（官网同页）：Replica Server 的管理、Replica 的分配与负载均衡调度、响应 Client 请求并提供最新的路由表（partition configuration）。Meta Server 所有状态持久化到 Zookeeper，通过 Zookeeper 选主；leader 故障后另一台 backup 立即抢到锁，从 Zookeeper 恢复状态成为新 leader。

Client Lib 的设计特点（官网同页）：配置简单（用户只需在配置文件指定 Meta Server 地址列表即可访问集群）；尽量直接与 Replica Server 交互、尽量少地访问 Meta Server 以避免单点问题；不依赖 Zookeeper。

💡 技术拓展：分布式 KV 存储常用的一致性/复制协议对比——

协议原理与特点代表系统
PacificA微软提出的强一致复制框架，配置管理（主副本成员）与数据复制分离，主节点驱动两阶段提交Pegasus（本文对象，官网明示）
Raft选主 + 日志复制的共识协议，强领导者模型，工程实现简单TiKV、etcd、CockroachDB
Paxos/Multi-Paxos经典共识协议，多提案者竞争，理论与工程门槛较高Chubby、Spanner
ZABZookeeper 专属的原子广播协议，主备广播ZooKeeper
最终一致（Dynamo 风格）W+R>N 仲裁读写，无主复制，可用性优先Cassandra、DynamoDB

Pegasus 实际采用 PacificA：数据写入复制到全部副本并确认后返回（见 3.2 读写路径），成员变更同样强一致，官网《概览》特性第一条原文可证。

3.2 读写路径

结合官网《系统架构》与《概览》特性描述，Pegasus 的读写路径如下：

  • 写路径：客户端经 Client Lib 按 HashKey 计算目标分片后，将写请求发往该分片主副本（primary replica）；每一份数据写入将分别复制到 3 个不同 ReplicaServer 上，待全部完成后才响应客户端（官网《概览》特性《数据的持久性》原文）。Replica Server 管理 commit log 并实现数据复制协议，保证副本间一致。
  • 读路径：Client Lib 直接与持有该分片的 Replica Server 交互读取，无需每次访问 Meta Server；只有路由信息（partition configuration）变化时才从 Meta Server 刷新，从而避免 Meta Server 成为单点（官网《系统架构》页 Client Lib 设计特点）。
  • 元数据路径：建表、扩缩容、故障转移等集群级操作由 Meta Server 处理，元数据与选主依赖 Zookeeper。

3.3 Collector（指标与可用性探测组件）

官方《系统架构》页的四部分之外，集群中还有一个 collector 角色：在 2.5.0 实测环境中，onebox 启动时包含 1 个 collector 进程（端口 34101），配置文件中 [pegasus.collector] 段配置了 available_detect_app = stat、usage_stat_app = stat（对 stat 表做可用性探测与用量统计），并支持热点检测开关 enable_detect_hotkey。首次启动后集群自动创建 stat 表（shell ls 实测 app_id=1、partition_count=4）供其使用。官方文档《高效运维》分类下的《可视化监控》即依赖 collector 与指标上报链路。

3.4 onebox 集群形态

官网《体验 Onebox 集群》页定义：onebox 让你在一台机器上体验 Pegasus 的集群式服务。启动时自动下载 ZooKeeper 安装包到本地隐藏目录 .zk_install 并启动本地 ZooKeeper（端口 22181），随后启动 3 个 MetaServer（端口 34601、34602、34603）和 3 个 ReplicaServer（端口 34801、34802、34803），并默认创建一个 temp 表。onebox 用于体验、实验与开发调试，官方明确"别指望 onebox 的性能有多好"，不是生产部署形态。2.5.0 实测中 onebox 还包含 1 个 collector 进程（端口 34101），共 7 个 server 进程。

四、核心概念

4.1 应用（app）与表（table）

Pegasus 对外以「表」组织数据，内部称为 app（application）。每张表有全局唯一的 app_id、表名 app_name、分区数 partition_count 与副本数 replica_count。2.5.0 实测 onebox 启动后初始表状态（shell ls 输出，collector 自动创建 stat 表 + 默认 temp 表）：

[general_info]
app_id  status     app_name  app_type  partition_count  replica_count  is_stateful  create_time          drop_time  drop_expire  envs_count
1       AVAILABLE  stat      pegasus   4                3              true         2026-10-14_17:41:42  -          -            0
2       AVAILABLE  temp      pegasus   8                3              true         2026-10-14_17:41:42  -          -            0

[summary]
total_app_count  : 2

建表时若未指定 -p（分区数），实测默认 partition_count=4（create t1 -r 3 后 ls 显示 t1 为 4 分区 3 副本）。表支持软删除：drop 后进入 DROPPED 状态，7 天后过期清理（实测 ls -a 中 t1 的 drop_expire 为 7 天后日期）。

4.2 分区（partition）与分区 ID（gpid）

官网《数据模型》页：Pegasus 使用一个特定的 hash 函数，对 HashKey 计算出一个 hash 值，然后对分片个数取模，就得到该数据对应的 Partition ID。因此 HashKey 相同的数据总是存储在同一个分片中。每个分片（partition）在集群内以 gpid 标识，格式为 <app_id>.<partition_index>（如 3.1 表示 app_id=3 表的第 1 号分区）。实测佐证：向 t1（app_id=3）写入 set hkey sortkey value 返回 app_id: 3、partition_index: 2；磁盘上每分片一个目录，命名为 <app_id>.<partition>.pegasus（实测存在 1.1.pegasus、2.0.pegasus、3.1.pegasus 等）。分区数支持运行中扩展，官方《高效运维》提供 Partition-Split 功能（文档目录实测可见）。

💡 技术拓展：分布式存储的分片路由策略对比——

策略原理特点与取舍
哈希取模（固定分片数）hash(key) mod 分片数 → 分区 ID分片数固定、路由计算 O(1)，扩容需分裂或迁移分片
一致性哈希哈希环 + 虚拟节点节点增减时仅相邻区间数据迁移，无全局重分布
范围分片（range）按 key 排序区间切分支持范围扫描，但易热点、需动态分裂

Pegasus 实际采用「哈希取模 + 固定分片数」（官网《数据模型》页原文），配合 Partition-Split 功能实现运行中分片分裂扩容；代价是不支持按 key 范围全局扫描（hash_scan 只能扫单个 HashKey 内的 SortKey 区间，full_scan 为全表扫描，见 Shell 篇实测）。

4.3 组合键：HashKey 与 SortKey

官网《数据模型》页：Pegasus 的数据模型就是 Key-Value 模型，不支持复杂的 Schema；但为增强表达能力，Key 被分裂为 HashKey 和 SortKey，即组合键（composite key，[HashKey, SortKey] -> Value），与 DynamoDB 的 composite primary key（partition key and sort key）类似。

  • HashKey：字节串，用于计算数据属于哪个分片（见 4.2）。C++ 客户端侧长度限制 64KB；Server 侧从 2.0.0 起可由 [replication] max_allowed_write_size 限制整个请求包大小，默认 1MB。
  • SortKey：字节串，用于数据在分片内的排序。内部存储到 RocksDB 时，将 HashKey 和 SortKey 拼在一起作为 RocksDB 的 key。因此同一 HashKey 下的多条数据按 SortKey 有序存放，这是 multi_get（整行读取）、hash_scan（SortKey 区间扫描）等接口的语义基础。
  • Value：字节串。

4.4 单机存储引擎 RocksDB

概览页明示底层使用 RocksDB 作为存储引擎。实测层面：每个分片（replica）在 Replica Server 上对应一个独立的 RocksDB 实例目录（如 onebox/replica1/data/replica/reps/3.1.pegasus/data/rdb/，内含 000003.log、000009.sst、CURRENT、IDENTITY、LOCK、LOG 等 RocksDB 标准文件），分片日志另有 shared log 目录（slog）。onebox 配置模板中未显式配置 rocksdb 参数段，全部走代码默认值。编译时可通过 --enable_rocksdb_portable 构建可移植的 rocksdb 二进制（run.sh 官方选项），规避预编译产物携带 AVX-512 指令导致的兼容性问题（详见《Ubuntu 22.04 源码编译部署 Apache Pegasus 2.5.0 指南》常见问题一节）。

4.5 decree（写版本号）

每条成功写操作在分片内获得一个单调递增的 decree 版本号，随命令回显返回。2.5.0 实测：set hkey sortkey value 后 decree=5，连续 set hkey sk2 v2、set hkey sk3 v3、incr、del 后 decree 依次为 6、7、9、10、11。它是复制协议下写顺序的体现，也可用于粗略判断写入次数。

五、功能特性全景

下表汇总官方文档目录（《用户接口》《高效运维》分类）与官网《概览》页明示的特性，来源列给出官方章节名；标「实测」的条目在 2.5.0 onebox 环境验证过。

特性说明来源
强一致三副本复制每份数据写入复制到 3 个 ReplicaServer，全部完成后才响应；PacificA 协议，支持强一致成员变更官网《概览》特性
自动负载均衡MetaServer 内置功能，让 Replica 在节点间均匀分布；不均衡时管理员可通过简单命令触发自动迁移官网《概览》特性、《高效运维/负载均衡》
冷备份可扩展的备份和恢复策略，存储位置可为 HDFS 或本地存储；文件系统上的快照数据可通过 pegasus-spark 做离线分析官网《概览》特性、《高效运维/冷备份》
duplication（跨机房同步）满足最终一致性的跨数据中心复制，本地集群数据写在短时间内到达远端集群，提升可用性、避免跨机房访问延迟官网《概览》特性、《高效运维/跨机房同步》
TTL数据存活时间控制，set 时可带 ttl 参数，ttl 命令查询官方文档《用户接口/TTL》；实测 ttl hkey sortkey 返回 Infinite
单行原子操作get/set/del 与 multi_get/multi_set/multi_del 等单行（同一 HashKey）操作原子性保证官网《数据模型》、《用户接口/单行原子操作》
Redis 适配官方提供 Redis 语义适配专章（见第六节）官方文档《用户接口/Redis 适配》
GEO 支持地理位置数据类型支持官方文档《用户接口/GEO 支持》
HTTP 接口服务端 HTTP 服务与 RPC 同端口，提供运维查询入口官方文档《用户接口/HTTP 接口》；实测 2.5.0 /meta/apps、/recentStartTime 可用
Backup Request备份请求：读请求同时发往主副本与备副本，先到先用，降低长尾延迟官方文档《高效运维/Backup Request》
流量控制（throttling）服务端限流能力，可按 RPC 类型拒绝超额请求官方文档《高效运维/流量控制》；实测配置模板含 rpc_request_throttling_mode = TM_REJECT
热点检测集群热点 partition 检测（collector 配置 enable_detect_hotkey）官方文档《高效运维/热点检测》
Manual Compact手动触发 RocksDB compaction官方文档《高效运维/Manual Compact 功能》
Usage Scenario按业务场景（如批量写/读多）调整存储行为官方文档《高效运维/Usage Scenario 功能》
Partition-Split运行中分片分裂扩容官方文档《高效运维/Partition-Split》
数据压缩存储数据压缩能力官方文档《高效运维/数据压缩》
Table 软删除drop 后表进入 DROPPED 状态保留 7 天，可 recall 恢复官方文档《高效运维/Table 软删除》；实测 ls -a 显示 DROPPED 与 7 天后 drop_expire
Table 环境变量表级 envs 配置（create -e 或后期设置）官方文档《高效运维/Table 环境变量》；实测 ls 表头含 envs_count
资源管理集群资源（磁盘/内存）管理官方文档《高效运维/资源管理》
故障恢复元数据恢复、Replica 数据恢复、坏盘检修、Zookeeper 迁移、Table 迁移官方文档《高效运维》各章
Replica Server 白名单接入层访问控制官方文档《高效运维/Replica Server 白名单》
监控无内置 WebUI；官方方案为 Prometheus + Grafana 可视化监控官方文档《高效运维/可视化监控》；实测 2.5.0 指标上报默认关闭（perf_counter_sink 为空，9092 端口无监听）

💡 说明：上表「说明」列为官方文档口径的概括，逐项细节请以对应官方章节为准；「实测」结论取自 2.5.0 onebox 环境，与官方文档一致。

六、Redis 协议兼容与差异

6.1 官方口径的兼容思路

官网《数据模型》页《Pegasus vs. Redis》一节：Pegasus 不像 Redis 一样支持丰富的 List/Set/Hash 等数据结构，但用户同样可以使用 Pegasus 实现类似的语义——将 HashKey 等同于 Redis 的 key，将 SortKey 作为 Hash 的 field（或 Set 的 member），即可实现 Redis 中 Hash（或 Set）的语义。同时官方文档《用户接口》分类下提供《Redis 适配》专章，描述在 Pegasus 上做 Redis 适配使用的方法，兼容范围以该官方章节为准。

6.2 命令族的对应关系（Shell 实测）

2.5.0 shell 提供与 Redis 同名且语义相近的单键命令：set、get、del、exist、incr、ttl；Pegasus 特有的是组合键带来的行级批量命令 multi_get/multi_get_sortkeys/multi_set/multi_del（对同一 HashKey 的多条 SortKey 操作，单行原子）。与 Redis 的主要差异：

  • 数据结构：不支持 Redis 原生 List/Set/Hash/ZSet 结构命令，语义靠 HashKey+SortKey 映射实现；
  • 键语法：所有数据命令的 key 都是 <hash_key> <sort_key> 两个参数，且 shell 数据命令不携带表名（需先 use <表>，实测把表名当 hash_key 传入会报 ERROR: parse value as ttl failed）;
  • 一致性：Pegasus 写入为强一致三副本确认（Redis 主从为异步复制），代价与延迟模型不同；
  • 持久化：Pegasus 数据天然持久化于 RocksDB 并有冷备份/duplication 等保障，无需额外配置 RDB/AOF。

6.3 客户端库

官方文档《客户端库》分类提供：Java、C++、Golang、Python、NodeJS、Scala 客户端（官方文档目录实测可见）。应用通过客户端库（而非 Redis 协议直连）访问集群，客户端只需配置 Meta Server 地址列表即可获得路由并直接与 Replica Server 通信。

七、版本 2.5.0 与适用场景

7.1 版本现状

  • 2.5.0 为当前最新稳定版：官网《版本发布》页（https://pegasus.apache.org/zh/docs/downloads/）版本列表排序尾部为 2.5.0，前有 2.4.0、2.3.0；GitHub 仓库最新 tag 为 v2.5.0，两者一致（2026-10 实测核实）。
  • 发行形态：官方以源码包发布（apache-pegasus-2.5.0-incubating-src.zip，4,377,166 字节，sha512 校验一致实测）；GitHub v2.5.0 release 页面无二进制附件。因此部署一律走源码编译，详见《Ubuntu 22.04 源码编译部署 Apache Pegasus 2.5.0 指南》。
  • 官方 Shell 工具文档明确标注「本文档基于 2.5.0 版本」，命令行为与本文实测一致。

7.2 适用场景

结合官网背景页（多级别数据安全保障、快速跨数据中心迁移、自动负载均衡、快速分片分裂）与特性清单，Pegasus 适合：

  • 海量结构简单的 KV/宽行数据（以 HashKey 组织一行、SortKey 组织列），要求低延迟且延迟稳定（写路径不依赖分布式文件系统）；
  • 对数据可靠性要求高、需要强一致复制的场景（三副本确认写入、冷备份、元数据/Replica 数据恢复体系）；
  • 异地/跨机房容灾与就近读写（duplication 最终一致复制）；
  • 需要平滑扩缩容与自动负载均衡的大规模在线存储（Partition-Split、greedy 负载均衡）。

7.3 局限与注意事项

  • 无内置 WebUI 管理界面：集群观测依赖 shell 命令行与 HTTP REST 接口，可视化依赖 Prometheus + Grafana（官方《可视化监控》方案）；2.5.0 指标上报默认关闭，需改配置开启。
  • onebox 仅用于体验与实验，官方明示不追求其性能，生产部署应按官方《集群部署》文档规划多机多节点。
  • 项目处于 Apache 孵化阶段（incubating），选型时请将社区成熟度与自身诉求结合评估。
  • 数据模型只有 KV 组合键，不支持二级索引等复杂 Schema（官方数据模型页口径）。

八、同类选型对比

💡 说明：下表以官网《概览》背景页对 Redis/HBase 的官方对比为锚点，其余为业界一般认知，供选型参考；最终决策请结合各产品官方文档与自身压测。

维度Apache Pegasus（本文对象）RedisHBaseCassandraTiKV
语言/运行时C++CJavaJavaRust
数据模型KV 组合键（HashKey+SortKey）丰富内存数据结构列族宽表宽列（CQL）分布式 KV（TiDB 底座）
存储RocksDB（本地盘）纯内存为主，持久化为辅HDFS 之上的 LSMLSM（本地盘）RocksDB（本地盘）
一致性PacificA 强一致（3 副本确认写）主从异步复制，不具备强一致（官网背景页口径）强一致可调最终一致（AP 风格）Raft 强一致
写路径依赖本地文件系统（官网明示，延迟稳定）内存HDFS（延迟受其影响）本地盘本地盘
横向扩展哈希分片 + Partition-Split + 自动负载均衡Cluster 分片Region 自动分裂一致性哈希虚拟节点Region 分裂
典型场景高吞吐强一致 KV、跨机房同步缓存/低延迟数据结构离线与海量宽表分析多写多活最终一致NewSQL 底座

关键差异：Redis 胜在数据结构与低延迟但弱持久弱一致；HBase 生态与宽表分析强但写路径依赖 HDFS；Cassandra 可用性优先牺牲强一致；TiKV 面向 NewSQL 场景；Pegasus 的差异化在「C++ + 本地盘 + 强一致三副本 + 跨机房同步 + 自动负载均衡」的组合，正对应官网背景页「弥补 Redis 与 HBase 之间的空白」的定位。

九、参考链接