KaiwuDB 运维实战05：数据库扩缩容：分布式集群的弹性之道

本文面向使用 KaiwuDB 分布式集群的开发者、DBA 和运维工程师，分享数据库扩缩容的基本原理与工程实践。文章内容包括：垂直扩展与水平扩展的区别、数据分片与数据重分布的工作机制、扩缩容过程中需要关注的一致性与成本问题，以及 KaiwuDB 集群扩缩容的完整操作指南——涵盖多副本集群与单副本集群的扩容方式（安装程序 / 命令行）、多副本集群的节点退役（缩容）流程、操作前后的检查清单和注意事项。你可以理解分布式集群弹性的实现原理，并能够在业务低峰期安全地完成 KaiwuDB 集群的扩容与缩容操作。

一、为什么数据库需要"弹性"

原因很简单，因为业务量是变化的。一个物联网平台可能在接入初期每天处理几百万条传感器数据，一年后这个数字可能增长百倍；也可能遇到项目结项、产线停产，负载大幅下降。如果数据库集群的资源配置固定不变，长期来看会出现两个问题：资源不够时，性能瓶颈拖累业务；资源过剩时，硬件和电力成本白白消耗。解决办法是让集群具备弹性：负载增长时增加资源，负载下降时回收资源。这引出一个前提问题——资源怎么加？

垂直扩展（Scale-Up） 是直觉上的做法：换更强的 CPU、加更大的内存、挂更大的磁盘。单机升级简单，但天花板明显，单机硬件有物理上限，而且扩容期间通常需要停机。水平扩展（Scale-Out） 是另一种思路：不换更强的机器，而是加更多的机器，让多台服务器共同承担负载。水平扩展的上限高得多，理论上可以无限加节点，但它对数据库架构有硬性要求——数据必须被拆分成可以分布到多台机器上的单元。

这就是数据分片（Sharding）的由来。分布式数据库将数据按规则切分为一个个分片（KaiwuDB 中称为 Range），分散存储在集群各节点上，每个分片再按副本数（如 三副本）冗余到不同节点。当集群增加节点时，系统可以把已有分片迁移到新节点上，让数据重新均匀分布，这个过程称为数据重分布（Rebalance）。重分布完成后，新节点开始承担读写负载，扩容才算真正生效。理解了这一层，就能看清扩缩容的两个关键工程问题：

数据怎么迁：分片是数据迁移的最小单元。迁移某个分片前，需要在目标节点准备好副本并同步数据，同步完成后再切换服务的"主副本"归属，整个过程必须保证数据强一致、业务不中断。

什么时候迁：迁移占用网络带宽和磁盘 IO。在业务高峰期执行重分布，会与正常业务竞争资源。因此扩缩容操作普遍建议安排在业务低峰期，并预留足够的磁盘空间——迁移期间数据尚未清理完成，源端和目标端会同时持有数据副本，磁盘使用量会临时升高。

缩容是扩容的逆过程，但风险不对称。扩容只是增加承载能力，而缩容要在移除节点的过程中保证数据不丢、服务不断。正确的做法不是直接关机，而是先让节点"退役"：拒绝新请求、允许存量请求完成、把该节点上的分片副本和租约逐一迁移到其他节点，确认该节点不再持有任何数据后，再将其移除。缩容也有一个底线：剩余节点数必须仍然满足副本数要求，否则部分分片将无处可迁，操作会一直挂起。

二、从“停机搬数据”到“在线弹性”

数据库扩缩容的实践也经历了一个演进过程。早期单机架构下，扩容就是换一台更大的机器，或者停机把数据迁移到新服务器上。这个过程通常需要数小时甚至数天，业务中断不可避免。主备架构出现后，扩容的思路变成了“加备库”。但主备之间的数据同步是单向的，备库加入后需要先做全量数据拷贝，拷贝完成才能开始增量同步。对于TB级的数据，这个“预热”过程可能持续数小时，期间备库无法承担读请求。

分布式数据库的成熟改变了局面。以Raft协议为代表的一致性协议，让多副本之间的数据同步变得自动化和可靠。新节点加入集群后，系统可以自动把部分副本迁移到新节点上，迁移过程不影响正在进行的读写操作。这就好比从“搬家时全家停业”变成了“一边营业一边搬”——业务感知不到，但容量已经悄悄增加了。

KaiwuDB的多副本集群正是基于这一路线：集群中的分片副本可以在节点之间自动迁移，扩容和缩容操作在集群可用状态下即可执行，即使发生扩缩容或节点故障，系统仍能正常执行DDL、DML、DQL等各类数据库操作。

三、KaiwuDB 集群的扩缩容能力

KaiwuDB 支持集群的动态扩容和缩容，不同集群类型的同集群类型的能力主要有以下三点差异：

这里有三点差异值得注意：

多副本集群扩容后自动重分布：新节点加入后，系统默认自动将现有数据均匀分布到所有节点，确保负载均衡。如需关闭自动重分布，可设置集群参数：

SETCLUSTER SETTING kv.allocator.ts_consider_rebalance.enabled=false;

重分布期间建议避免频繁执行 ALTER 语句，以免延长重分布时间。

单副本集群扩容不做存量迁移：数据重分布仅对新建表生效，已有数据仍留在原节点。这意味着单副本集群扩容主要提升的是新建数据的承载能力和整体吞吐，存量热点不会自动均衡。有存量均衡需求的生产环境，建议采用多副本集群。

操作前的通用注意事项：

• 集群节点数必须在许可证允许范围内，超出上限时扩容将被拒绝；

• 扩缩容期间，时序索引相关的 DDL 操作（如 CREATE INDEX、DROP INDEX）可能返回超时错误，操作完成后重试即可；

• 扩缩容期间因数据迁移需要，磁盘使用量可能临时增加，完成后恢复正常；

• 建议在业务低峰期执行操作。

四、KaiwuDB 集群扩容实操

KaiwuDB 提供安装程序扩容和命令行扩容两种方式，用户可以根据不同需求来选择。安装程序扩容（尤其命令行模式）流程标准化、自动完成参数配置，适合大多数场景；命令行扩容适合已有自动化运维体系、需要精细控制启动参数（如自定义 store 路径、多 join 地址）的场景。两者对安全模式的证书要求不同，需按部署方式提前准备。无论选择哪种方式，开始前均需满足：

• 待扩容节点未安装 KaiwuDB；

• 目标集群处于运行状态；

• 当前节点数未达到许可证上限。

4.1 安装程序扩容

KaiwuDB 安装程序提供三种交互模式，均支持"安装 KaiwuDB 并加入集群"，适用于多副本集群和单副本集群，操作流程一致：

命令行模式（-c / --cli）：执行安装程序后输入 3 选择"安装 KaiwuDB 并加入集群"，再按集群类型选择"加入单副本集群"或"加入三副本集群"，依次填写目标集群任一节点地址与服务端口（默认 26257）、CA 证书路径（非安全模式可跳过），安装程序生成配置文件模板并打开编辑器，确认保存后自动完成安装和入群。

[global] secure_mode=tls # 安全模式，需与目标集群一致 rest_port=8080 # Admin UI 端口 kaiwudb_port=26257 # 数据库服务端口 brpc_port=27257 # 数据传输端口 data_root=/var/lib/kaiwudb # 数据目录 [node1] host=192.168.122.224 # 待扩容节点 IP port=22 # SSH 端口 user=admin # SSH 用户 passwd=****** # SSH 密码

终端图形交互模式（-i / --interact）：在菜单中选择"安装 KaiwuDB 并加入集群"，逐项设置安全模式、各端口、数据目录、目标集群地址与端口、待扩容节点信息，配置完成后开始安装。

可视化 GUI 模式（-g / --gui）：向导式操作，在参数配置页设置与目标集群一致的参数，在节点管理页添加待扩容节点并勾选"加入集群"，填写目标集群参数后开始安装。

三种模式安装完成后，均通过以下命令检查新节点是否成功加入：

kw-status

4.2 命令行扩容

登录待扩容节点，按集群类型执行加入命令。多副本集群使用 kwbase start，单副本集群使用 kwbase start-single-replica（两者参数相同，区别在于副本机制不同）。以非安全模式的多副本集群为例：

<kwbase_path>/kwbase start\--insecure\--store=<data_dir>\--brpc-addr=:27257\--listen-addr=<new_node_ip>:<kaiwudb_port>\--http-addr=<new_node_ip>:<rest_port>\--join=<node_address_list>\--background

参数说明：

加入后通过 kwbase node status（或监控平台 / kw-status）确认节点状态。多副本集群此时会自动触发数据重分布，待分片均衡后，新节点开始承担负载。

五、KaiwuDB 集群缩容实操

KaiwuDB 目前支持多副本集群和双副本集群的命令行缩容方式。用户主动移除节点时，KaiwuDB 会允许节点完成正在执行的请求，拒绝任何新的请求，同时将该节点上的分区副本和分区租约迁移到其他节点，以确保数据的平稳迁移。节点可以根据实际需求选择永久移除，以最大程度地保障系统的可用性和数据的完整性。以下几点需要重点关注：

移除节点时，必须确保有其他节点可以接管该节点的分区副本。如果没有可用的其他节点，移除操作将无限期挂起。

KaiwuDB 多副本集群采用三副本机制，最小集群节点数为 3，不允许进一步缩容。

双副本集群缩容时，退役数据节点要求集群中至少存在 3 个数据节点；退役仲裁节点要求集群中至少存在 2 个仲裁节点。不满足上述条件时，退役操作将失败。

如果之前通过 CONFIGURE ZONE 语句设置了副本约束，且约束规则中包含待缩容节点，可能会影响集群缩容的正常运行。此时需要重新配置约束规则，将待缩容节点从规则中移除，集群缩容即可恢复正常。

节点退役后如需再次加入集群，需要先清空数据目录，作为新节点重新加入集群。

5.1 缩容前提条件

• 集群内所有节点均处于存活状态（is_available 和 is_live 均为 true），可通过 kw-status 或 kwbase node status 确认；

• 已通过监控平台或命令获得待退役节点的 ID；

集群中不存在不可用分区或副本不足的分区，可通过以下 SQL 检查：

SELECTsum((metrics->>'ranges.unavailable')::DECIMAL)::INTASranges_unavailable,sum((metrics->>'ranges.underreplicated')::DECIMAL)::INTASranges_underreplicatedFROMkwdb_internal.kv_store_status;

5.2 操作步骤

1. 执行节点退役命令（在集群任一节点执行）：

# 非安全模式[kwbase_path]/kwbasenodedecommission<node_id>--insecure[--host=<address_of_any_alive_node>]# TLS 安全模式[kwbase_path]/kwbasenodedecommission<node_id>--certs-dir=<cert_path>[--host=<address_of_any_alive_node>]# TLCP 安全模式[kwbase_path]/kwbasenodedecommission<node_id>--certs-dir=<cert_path>[--host=<address_of_any_alive_node>]--tlcp

2. 等待迁移完成。通过以下命令观察退役进度，节点状态变为 decommissioning，其上的副本数缩减到 0 时退役完成：

# 非安全模式[kwbase_path]/kwbasenodestatus--insecure[--host=<address_of_any_alive_node>]--decommission# TLS 安全模式[kwbase_path]/kwbasenodestatus --certs-dir=<cert_path>[--host=<address_of_any_alive_node>]--decommission# TLCP 安全模式[kwbase_path]/kwbasenodestatus --certs-dir=<cert_path>[--host=<address_of_any_alive_node>]--decommission--tlcp

3.（可选）如需将退役节点彻底移出集群，可执行以下命令：

# 非安全模式[kwbase_path]/kwbase quit--insecure--host=<decommissioned_node># TLS 安全模式[kwbase_path]/kwbase quit --certs-dir=<cert_path>--host=<decommissioned_node># TLCP 安全模式[kwbase_path]/kwbase quit --certs-dir=<cert_path>--host=<decommissioned_node>--tlcp

4.（可选）确认移除结果：通过 kw-status 或 kwbase node status 确认节点已不在集群中。

# TLS 安全模式[kwbase_path]/kwbasenodestatus --certs-dir=<cert_path>[--host=<address_of_any_alive_node>]# TLCP 安全模式[kwbase_path]/kwbasenodestatus --certs-dir=<cert_path>[--host=<address_of_any_alive_node>]--tlcp# 非安全模式[kwbase_path]/kwbasenodestatus--insecure[--host=<address_of_any_alive_node>]

本文相关术语表

本文 FAQ

Q1：KaiwuDB 扩容后数据会自动均衡吗？

多副本集群会自动触发重分布，将现有数据均匀分布到所有节点；单副本集群的重分布仅对新建表生效，已有数据不迁移。如果关闭了自动重分布参数（kv.allocator.ts_consider_rebalance.enabled = false），多副本集群也不会自动均衡。

Q2：KaiwuDB 扩容期间业务会受影响吗？

正常情况下不中断，但数据迁移会占用网络带宽和磁盘 IO，建议业务低峰期执行。期间时序索引类 DDL 可能返回超时错误，操作完成后重试即可。磁盘使用量会因迁移临时升高，需预留空间。

Q3：KaiwuDB 缩容操作一直挂起是什么原因？

最常见的原因是没有足够的节点接管待退役节点的分片副本。多副本集群最小节点数为 3，缩容到 3 节点以下会被拒绝；另外，如果通过 CONFIGURE ZONE 设置了包含该节点的副本约束，也会阻塞迁移，需先移除约束。

Q4：KaiwuDB 退役过的节点还能重新加入集群吗？

可以，但必须先清空该节点的数据目录，然后作为全新节点执行扩容流程加入。

写在最后

扩缩容是分布式数据库"弹性"最直接的体现，但它的本质不是简单的加减机器，而是数据的迁移与再均衡。扩容的关键在于分片能否自动、平滑地重分布；缩容的关键在于数据能否先迁走、节点再退役。KaiwuDB 多副本集群把这两条路径都做成了自动化流程：扩容后自动均衡，缩容时自动迁移副本和租约。