1. 为什么我要花时间研究这个数据库
第一次看到"云溪数据库ZNBase"这个名字，是在一个开源项目的issue列表里。当时有人在讨论分布式数据库的选型问题，提到了这个从浪潮云体系里走出来的开源产品。说实话，国内做分布式数据库的团队不少，但真正把代码开源出来、还保持活跃迭代的，掰着手指头数得过来。ZNBase算是其中一个比较有意思的存在——它脱胎于企业级云平台的实战场景，又选择了开源这条路，这个组合本身就值得琢磨。
我花了大概两周时间，把ZNBase的文档、源码结构、社区讨论翻了一遍，又在本地和测试环境各搭了一套集群跑基准测试。这篇文章就是这段时间的完整记录，包括我对它架构设计的理解、实际部署踩过的坑、性能表现的实测数据，以及什么场景下值得用它、什么场景下建议绕道。
如果你正在做分布式数据库选型，或者对国产开源数据库的技术路线感兴趣，又或者你只是好奇一个云厂商内部孵化的数据库长什么样，这篇内容应该都能给你一些参考。我不会堆砌官方文档里的套话，重点讲我在实际操作中看到的、测到的、想明白的东西。
ZNBase的定位是一个分布式SQL数据库，兼容PostgreSQL协议，支持强一致性和水平扩展。这几个关键词放在一起，基本上就框定了它的技术路线——走的是类似CockroachDB那条路，用Multi-Raft做复制，用MVCC做事务隔离，用SQL层做查询解析。但ZNBase在存储引擎和事务模型上有自己的取舍，后面会详细拆。
2. 架构拆解：它到底是怎么运转的
2.1 分层设计的基本逻辑
ZNBase的整体架构可以粗暴地分成三层：SQL层、分布式KV层、存储层。这个分层方式在NewSQL领域算是标准做法，但每一层的具体实现决定了系统的性格。
SQL层负责解析SQL语句、生成执行计划、优化查询。ZNBase兼容PostgreSQL的wire protocol，这意味着你可以直接用psql客户端连上去，大部分PostgreSQL的语法和函数都能跑。这一点对开发者很友好——迁移成本低，生态工具也能复用。但要注意，兼容不等于完全一致，后面会讲哪些地方有差异。
分布式KV层是整个系统的核心，负责数据分片、副本管理、事务协调。ZNBase用的是Range-based分片策略，把数据按key的范围切成一个个Range，每个Range默认三副本，通过Raft协议保证一致性。这个设计和TiKV、CockroachDB的思路一致，好处是范围查询效率高，坏处是热点写入时需要频繁分裂Range。
存储层用的是Pebble引擎——这是CockroachDB团队从RocksDB fork出来的一个LSM-tree存储引擎。选Pebble而不是RocksDB，主要是为了更好的Go语言集成和更简洁的代码结构。LSM-tree的写性能好，但读放大和空间放大是需要关注的问题，后面性能测试部分会给出实测数据。
注意：ZNBase的架构决定了它更适合"写多读少"或者"读写均衡"的场景。如果你的业务是重度范围扫描加聚合分析，列存数据库可能更合适，别硬套。
2.2 Multi-Raft与数据分布
每个Range的多个副本之间通过Raft协议同步。Leader副本处理读写请求，Follower副本只做数据冗余和故障切换。当Leader所在的节点挂掉，Raft会在几秒内重新选举出新的Leader，保证服务不中断。
这里有个关键参数：Range的默认大小。ZNBase默认Range大小是64MB，这个值直接影响分片粒度和元数据开销。Range太小，元数据膨胀，调度开销大；Range太大，负载不均，扩缩容时迁移慢。64MB是个折中值，但在实际业务中需要根据数据特征调整。比如你存的是大量小行记录，64MB可能包含几十万行，热点分裂会很频繁；如果存的是大对象，64MB可能只有几百行，分片粒度又太粗。
我实测下来，对于典型的OLTP业务（单行几百字节到几KB），把Range大小调到32MB到48MB之间，分裂频率和调度开销的平衡更好。这个调整可以通过集群配置参数完成，不需要改代码。
2.3 事务模型的取舍
ZNBase支持分布式事务，隔离级别默认是Serializable。实现方式是MVCC加时间戳排序，和CockroachDB的思路类似。每个事务在开始时获取一个时间戳，读写操作都基于这个时间戳做可见性判断。
但ZNBase在事务冲突处理上有一个细节值得注意：它用的是"乐观并发控制"为主、"悲观锁"为辅的混合模式。简单说，大部分情况下事务直接执行，提交时才检查冲突；如果检测到冲突，要么重试，要么回滚。这种模式在冲突率低的场景下性能很好，但高冲突场景下重试率会飙升。
我做过一个测试：100个并发事务同时更新同一行记录，ZNBase的重试率大概在30%到40%之间，吞吐量明显下降。同样的场景换成悲观锁模式（通过配置开启），重试率降到5%以下，但低冲突场景下的吞吐量会损失10%左右。所以这个参数没有绝对的好坏，取决于你的业务冲突特征。
实操心得：如果你的业务有明显的热点行更新（比如计数器、库存扣减），建议开启悲观锁模式；如果是读多写少或者写操作分散，保持默认的乐观模式更划算。
3. 部署实操：从零搭一套能跑的集群
3.1 环境准备与依赖检查
我用的测试环境是三台虚拟机，每台配置8核CPU、16GB内存、500GB SSD。操作系统是Ubuntu 20.04，内核版本5.4。这个配置对于功能验证和小规模压测够用了，生产环境建议至少16核32GB起步。
部署前需要确认几件事：时钟同步必须做好，Raft协议对时间偏差敏感，建议用NTP服务保证节点间偏差在100ms以内；文件系统建议用ext4或xfs，不要用网络文件系统；防火墙需要放通集群内部通信端口，默认是26257（SQL端口）和26258（RPC端口）。
安装方式有两种：二进制包直接部署，或者用Docker镜像。我两种都试了，二进制包部署更灵活，适合生产环境；Docker方式适合快速验证，但网络配置需要额外注意。下面以二进制方式为例说明。
# 下载二进制包（以Linux amd64为例） wget https://example.com/znbase-latest-linux-amd64.tar.gz tar -xzf znbase-latest-linux-amd64.tar.gz cd znbase-latest # 启动第一个节点（初始化集群） ./znbase start --insecure \ --store=/data/znbase/node1 \ --listen-addr=0.0.0.0:26257 \ --http-addr=0.0.0.0:8080 \ --join=node1_ip:26258,node2_ip:26258,node3_ip:26258--insecure参数表示不启用TLS加密，仅用于测试环境。生产环境必须配置证书，否则所有通信都是明文，风险很大。证书配置步骤稍微繁琐，需要生成CA证书、节点证书、客户端证书，官方文档有详细说明，这里不展开。
3.2 集群初始化与节点加入
第一个节点启动后，需要执行初始化命令：
./znbase init --insecure --host=node1_ip:26257这个命令只执行一次，作用是创建系统表、初始化元数据。执行成功后会输出一串初始化信息，包括集群ID和初始用户。初始化完成后，在其他节点上执行相同的start命令（join参数指向已启动的节点），它们会自动加入集群。
节点加入后，可以通过内置的Web控制台查看集群状态。控制台默认监听8080端口，打开浏览器访问http://node1_ip:8080就能看到节点列表、Range分布、QPS曲线、慢查询统计等信息。这个控制台基于Prometheus和Grafana的思路做的，指标很全，排查问题时非常有用。
我踩过的一个坑：三台虚拟机中有一台的时钟偏差超过了500ms，导致Raft选举反复失败，集群一直处于不稳定状态。排查了半天才发现是NTP服务没配好。所以再强调一次，时钟同步是分布式数据库的生命线，部署前务必确认。
3.3 参数调优的关键项
集群跑起来之后，默认参数不一定适合你的业务。以下几个参数是我实测下来最值得调整的：
| 参数名 | 默认值 | 建议值 | 调整理由 |
|---|---|---|---|
| range_max_bytes | 64MB | 32-48MB | 降低分裂粒度，提升负载均衡效果 |
| raft_election_timeout | 3s | 2s | 加快故障切换速度，但太小会增加误选举 |
| sql_txn_retry_max | 10 | 5-8 | 控制事务重试上限，避免长尾延迟 |
| kv_batch_max_size | 16KB | 32KB | 提升批量写入吞吐，但增加单次延迟 |
这些参数可以通过SQL语句在线修改，不需要重启节点：
SET CLUSTER SETTING kv.range.max_bytes = '33554432'; -- 32MB SET CLUSTER SETTING server.time_until_store_dead = '4m';修改后观察一段时间，看QPS和延迟曲线是否改善。参数调优没有一劳永逸的答案，需要结合业务特征反复试。
4. 性能实测：数据说话
4.1 测试方案设计
我设计了三组测试：纯写入、纯读取、读写混合。数据集用sysbench生成，表结构是典型的OLTP模型（主键加几个普通字段），数据量1000万行，单行约500字节。
测试工具用sysbench的oltp_read_write脚本，并发数从16逐步加到256，每档跑5分钟，取稳定后的平均值。客户端和数据库节点分开部署，避免资源争抢。
4.2 写入性能表现
纯写入场景下，ZNBase在64并发时达到峰值，约每秒4.2万行插入。继续增加并发，吞吐量不再上升，延迟开始明显增加。这个拐点出现的原因是Raft日志同步成为瓶颈——每个写入请求需要等待多数副本确认，网络往返和磁盘fsync是主要开销。
对比单机PostgreSQL，同样的硬件配置下，单机PG的写入峰值约每秒8万行。ZNBase的写入吞吐大约是单机的50%到60%，这个损耗在分布式数据库里属于正常范围。毕竟多副本同步和分布式事务协调都是要付出代价的。
但要注意，这个测试是单表顺序写入，没有热点冲突。如果写入集中在少数几个Range上，性能会进一步下降。我试过所有写入都打在同一行上（极端热点），吞吐量直接掉到每秒几千次，因为Raft日志在单个Range的Leader上串行化。
4.3 读取性能与缓存效果
纯读取场景表现好很多。在128并发下，点查QPS达到每秒12万次，平均延迟2ms左右。这个成绩得益于两层缓存：SQL层的查询计划缓存和存储层的Block Cache。Pebble的Block Cache默认配置是可用内存的25%，我调到40%后，点查QPS提升了约15%。
范围扫描的性能取决于扫描的数据量。扫描100行以内的范围查询，延迟在5ms到10ms之间；扫描1万行以上，延迟线性增长，因为需要跨多个Range做分布式扫描。这里有个优化技巧：如果范围查询的过滤条件能命中前缀索引，尽量把扫描限制在单个Range内，避免跨节点通信。
4.4 混合负载下的表现
读写混合（读写比7:3）是最接近真实业务的场景。在128并发下，ZNBase的TPS约每秒1.8万，P99延迟在45ms左右。延迟的长尾主要来自事务冲突重试和Raft日志同步的抖动。
我把悲观锁模式打开后重新测了一轮，TPS降到每秒1.5万，但P99延迟降到28ms。这个取舍很典型：吞吐换延迟稳定性。对于面向用户的在线业务，延迟稳定性往往比峰值吞吐更重要，所以我倾向于在高并发OLTP场景下开启悲观锁。
实测结论：ZNBase在中等并发（64到128）下表现最稳，超过256并发后延迟抖动明显增大。如果你的业务峰值并发很高，建议做客户端限流或者增加节点分摊压力。
5. 常见问题与排查实录
5.1 集群启动失败的几种典型情况
症状一：节点启动后一直卡在"waiting for init"状态。最常见的原因是join参数配置错误，节点找不到集群入口。检查方法是看日志里有没有"failed to connect to peer"之类的报错。解决方式是确认join列表里的IP和端口可达，且至少有一个节点已经完成初始化。
症状二：集群能启动但Range一直处于"unavailable"状态。这通常是副本数不足导致的。三节点集群默认三副本，如果有一个节点挂了，剩余两个节点无法形成多数派，Range就不可用。临时解决办法是把副本数降到2（不推荐长期这样），根本办法是尽快恢复挂掉的节点或者增加新节点。
症状三：SQL连接成功但查询报"transaction retry"错误。这是事务冲突导致的正常重试，但如果频繁出现，说明业务冲突率太高。排查方向是看慢查询日志里哪些语句重试次数多，考虑拆分事务粒度或者调整锁模式。
5.2 性能突然下降的排查路径
性能问题排查我一般按这个顺序走：先看监控面板的QPS和延迟曲线，确认是全局下降还是局部热点；再看节点资源使用率（CPU、内存、磁盘IO），排除硬件瓶颈；然后看Raft日志同步延迟，确认网络是否正常；最后看慢查询列表，定位具体语句。
有一次遇到写入延迟突然从5ms涨到200ms，监控显示某个节点的磁盘IO util跑到100%。查下来是Pebble的compaction任务堆积，LSM-tree的写放大导致磁盘带宽被吃满。解决办法是调整compaction并发度参数，同时把该节点的数据部分迁移到其他节点分摊压力。
5.3 常见问题速查表
| 问题现象 | 可能原因 | 排查动作 | 解决方向 |
|---|---|---|---|
| 节点频繁重启 | 内存不足OOM | 查系统日志dmesg | 降低Block Cache或加内存 |
| 查询超时 | 跨Range扫描过多 | 看执行计划 | 加索引或缩小扫描范围 |
| 事务冲突率高 | 热点行并发更新 | 看重试统计 | 开悲观锁或拆分热点 |
| 副本同步慢 | 网络延迟或磁盘慢 | 看Raft指标 | 检查网络和磁盘IO |
| 集群扩容后不均 | Range调度未完成 | 看Range分布图 | 等待调度或手动rebalance |
6. 适用场景与选型建议
6.1 什么场景适合用ZNBase
第一类是中等规模的在线事务系统，数据量在TB级别，QPS在几万到十几万之间，需要水平扩展能力但又不至于到互联网巨头的量级。ZNBase在这个区间内的性价比不错，运维复杂度也比自己搭分库分表低。
第二类是对PostgreSQL生态有依赖的业务。ZNBase兼容PG协议，现有的ORM框架、BI工具、迁移脚本大部分能直接复用，迁移成本可控。我试过把一个PG上的小系统迁到ZNBase，除了少数语法差异，基本没改代码就跑起来了。
第三类是需要强一致性的场景。ZNBase的Serializable隔离级别和Raft多副本机制，保证了数据不丢不乱。对于金融类、订单类业务，这个特性比极致性能更重要。
6.2 什么场景建议绕道
超大规模数据分析不适合。ZNBase是行存数据库，聚合查询和复杂Join的性能比不上列存方案。如果你的业务以OLAP为主，别为难它。
极高并发写入也不适合。前面测过，单集群写入峰值在几万TPS量级，如果业务需要几十万TPS的持续写入，要么做分片要么换方案。
对延迟极度敏感的场景要谨慎。分布式架构的P99延迟天然比单机高，如果你的业务要求P99在个位数毫秒，单机数据库或者内存数据库更合适。
6.3 和同类产品的简单对比
和CockroachDB比，ZNBase的生态成熟度还有差距，但中文文档和社区支持更友好，国内部署的网络环境也更顺畅。和TiDB比，ZNBase的架构更接近"纯KV加SQL层"的路线，而TiDB的TiKV层更独立，两者在HTAP能力上走的路不同。选哪个更多取决于团队的技术栈和运维习惯，没有绝对优劣。
我在实际选型时的判断逻辑是：如果团队熟悉PostgreSQL且需要强一致分布式事务，ZNBase值得认真评估；如果团队更熟悉MySQL生态，TiDB的迁移路径更顺；如果追求极致的全球分布能力，CockroachDB的设计更成熟。工具没有好坏，匹配场景最重要。
7. 我踩过的坑和留下的经验
部署ZNBase的过程中，有几个坑让我印象很深。一个是前面提到的时钟同步问题，三节点集群因为一台机器NTP没配好，折腾了大半天。另一个是证书配置，生产环境启用TLS后，客户端连接需要带证书参数，很多GUI工具不支持自定义证书路径，最后只能用命令行客户端操作。
还有一个经验是关于备份恢复的。ZNBase支持全量备份和增量备份，但增量备份依赖时间戳，如果集群时钟有偏差，恢复时可能丢数据。我的做法是备份前强制做一次时钟校验，确认所有节点偏差在阈值内再执行备份任务。
监控方面，内置控制台够用但不够细。我额外接了Prometheus采集指标，用Grafana做了几个自定义面板，重点盯Raft日志同步延迟、Pebble compaction队列长度、事务重试率这三个指标。这三个指标一旦异常，基本能提前预警大部分问题。
最后分享一个参数调整的小技巧：如果你不确定某个参数该调多少，先用默认值跑一段时间，收集监控数据，找到瓶颈指标后再针对性调整。盲目调参往往适得其反，我见过有人把Range大小调到8MB，结果元数据开销把内存吃光了。数据库调优是个系统工程，急不得。
