KWDB多副本集群保姆级部署：从环境准备到高可用验证的完整实践

在物联网和工业互联网场景中，数据的高可用性和一致性是系统稳定运行的生命线。KWDB作为面向AIoT场景的新一代分布式多模数据库，支持在同一实例中同时处理时序数据和关系数据，其多副本集群架构通过跨节点复制机制，实现了故障自动转移和数据强一致性。

多副本集群与单副本集群的核心差异在于数据冗余度。多副本集群在同一机房的多个节点上运行，每份数据默认保存3份副本，副本分布在不同节点上。这种设计使系统在单个节点发生故障时仍能通过多数投票机制维持服务，至少需要2个副本保持可用状态。相比之下，单副本集群虽然写入性能更优，但不具备高可用能力，节点故障时数据写入和查询可能直接失败。

本文将完整呈现KWDB多副本集群的部署流程，从硬件规划、操作系统准备、SSH免密配置，到集群初始化、状态验证和高可用测试，为读者提供一份可直接参照的操作指南。

一、部署前的环境规划

1.1 硬件规格要求

KWDB多副本集群的每个节点都需要独立的硬件资源。根据官方部署准备文档，单节点的最低配置建议为4核CPU和8GB内存。对于数据量大、复杂工作负载、高并发或高性能场景，需要配置更高的CPU和内存资源以确保系统高效运行。

磁盘方面，KWDB推荐使用SSD或NVMe设备，尽量避免使用NFS、CIFS、CEPH等共享存储。磁盘必须能够实现500 IOPS和30 MB/s的处理效率。官方明确不建议使用HDD部署分布式集群版本，因为机械硬盘的随机I/O性能难以满足分布式数据库的并发访问需求。

文件系统建议使用ext4。KWDB系统自身启动占用的磁盘容量低于1GB，实际所需磁盘大小主要取决于用户的业务量。

一个关键的规划原则是：为了提高可用性并降低数据丢失风险，建议在单台计算机上只运行一个节点。由于KWDB采用跨节点复制机制，如果一台计算机同时运行多个节点，当计算机发生故障时，多个节点同时失效的概率大幅增加，更有可能导致数据丢失。

1.2 操作系统与依赖

KWDB支持在多种操作系统上部署，包括Ubuntu 20.04/22.04/24.04、CentOS 7、openEuler、UOS 1050e/1060e/1070e等。本文以Ubuntu 22.04为例进行演示。

裸机部署需要在目标机器上安装必要的依赖库。Debian系列系统需要libc6不低于2.28版本，libgcc1或libgcc-s1不低于7.3.0版本，libstdc++6不低于7.3.0版本。如果目标机器不能联网，需要预先下载好依赖文件并复制到目标机器上进行离线安装。

1.3 端口规划

KWDB服务默认使用三个端口：

数据库Web服务端口默认为8080。数据库服务端口、节点监听端口和对外连接端口默认为26257。时序引擎间的brpc通信端口，用于节点间通信，默认为27257。

如需使用其他端口，可在安装部署过程中进行修改。

二、节点基础环境配置

以下操作需要在集群的每个节点上执行。

2.1 主机名与hosts配置

为每个节点设置唯一的主机名，便于集群内部识别和通信。以三节点集群为例：

bash 复制代码

# 在node1上执行
sudo hostnamectl set-hostname node1

# 在node2上执行
sudo hostnamectl set-hostname node2

# 在node3上执行
sudo hostnamectl set-hostname node3

随后在每个节点的/etc/hosts文件中添加集群所有节点的IP和主机名映射：

bash 复制代码

vi /etc/hosts

添加以下内容（IP地址根据实际环境调整）：

复制代码

192.168.3.101 node1
192.168.3.102 node2
192.168.3.103 node3

2.2 时钟同步配置

KWDB采用中等强度的时钟同步机制来维持数据一致性。当节点检测到自身的机器时间与集群中至少50%的节点的机器时间的误差值超过集群最大允许时间误差值（默认为500ms）的80%时，该节点会自动停止，从而避免违反数据一致性，带来读写旧数据的风险。

因此，每个节点都必须运行NTP或systemd-timesyncd等时钟同步软件，防止时钟漂移得太远。以Ubuntu 22.04为例：

bash 复制代码

# 安装systemd-timesyncd
sudo apt update
sudo apt install systemd-timesyncd

# 设定时区为东八区
sudo timedatectl set-timezone Asia/Shanghai

# 启用NTP自动时间同步
sudo timedatectl set-ntp on

# 启动并设置开机自启
sudo systemctl start systemd-timesyncd
sudo systemctl enable systemd-timesyncd

# 验证状态
timedatectl status

2.3 SSH免密登录配置

KWDB的部署脚本需要从部署节点通过SSH连接到其他节点执行安装和配置操作。因此，需要配置部署节点到所有节点（包括自身）的SSH免密登录。

以node1作为部署节点，执行以下操作：

bash 复制代码

# 在node1上生成密钥对（密码留空）
ssh-keygen -f ~/.ssh/id_rsa -N ""

# 将公钥分发到所有节点
ssh-copy-id -f -i ~/.ssh/id_rsa.pub -o StrictHostKeyChecking=no node1
ssh-copy-id -f -i ~/.ssh/id_rsa.pub -o StrictHostKeyChecking=no node2
ssh-copy-id -f -i ~/.ssh/id_rsa.pub -o StrictHostKeyChecking=no node3

验证免密登录是否生效：

bash 复制代码

ssh node1
ssh node2
ssh node3

如果无需输入密码即可登录，说明配置成功。

三、安装KWDB

3.1 下载安装包

从KWDB官方发布页面下载对应系统环境的安装包。以Ubuntu 22.04 x86_64为例：

bash 复制代码

wget https://gitee.com/kwdb/kwdb/releases/download/V2.2.0/KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz

解压安装包：

bash 复制代码

tar -xzvf KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz

解压后进入安装目录，可以看到deploy.sh、deploy.cfg、add_user.sh等脚本文件以及packages目录。

3.2 安装依赖

在部署节点上安装必要的依赖：

bash 复制代码

sudo apt update
sudo apt install cmake
sudo snap install go --classic
sudo apt install libprotobuf-dev

3.3 执行安装

进入安装包目录，为deploy.sh脚本添加执行权限，然后执行多副本集群安装命令：

bash 复制代码

chmod +x ./deploy.sh
./deploy.sh install --multi-replica

执行安装命令后，系统会根据deploy.cfg中的配置将KWDB安装到各节点。安装完成后，系统会提示重新加载systemd守护进程的配置文件：

bash 复制代码

systemctl daemon-reload

四、集群初始化与启动

4.1 初始化集群

安装完成后，需要初始化并启动集群：

bash 复制代码

./deploy.sh cluster --init

集群初始化和启动大约需要10秒左右。在此期间，如果有节点死亡，可能会导致集群无法触发高可用机制。因此，建议在初始化期间确保所有节点处于正常运行状态。

4.2 查看集群状态

集群启动后，通过以下命令查看节点状态：

bash 复制代码

./deploy.sh cluster --status

返回信息包含节点的关键状态字段。id表示节点ID，address表示节点地址，build表示节点的KWDB版本，started_at表示节点启动时间。最关键的字段是is_available和is_live，两者均为true表示节点正常运行，均为false表示节点异常。

4.3 配置开机自启动

为避免系统重启后需要手动启动KWDB，可以配置开机自启动：

bash 复制代码

systemctl enable kaiwudb

需要注意的是，系统重启后，如果当前节点与其他节点时钟相差大于500ms，可能会导致KWDB自启动失败。此时需要先进行时钟同步，再手动启动KWDB。

五、高可用机制验证

5.1 正常运行状态

KWDB多副本集群默认采用3副本机制。集群启动后，副本和leaseholder均匀分布在所有节点上，确保数据的高可用性和负载均衡。

理解几个核心概念有助于后续的验证测试。数据分片是集群高可用性和数据迁移的最小单元。每个数据分片默认有3个副本。主副本负责处理该分片的读写请求，通过RAFT协议选举产生。

5.2 单节点状态异常测试

模拟一个节点因网络断开、操作系统故障或磁盘故障导致状态变为异常。将node3的kaiwudb服务停止：

bash 复制代码

# 在node3上执行
systemctl stop kaiwudb

查看集群状态，node3的is_available和is_live均变为false。系统会开始迁移该节点的leaseholder，迁移期间数据查询和DML操作可能受影响，DDL操作可能会报错。

验证服务写入和查询是否正常。在正常节点上执行SQL操作，观察响应时间。测试表明，在单节点异常的情况下，INSERT和SELECT操作仍可正常执行。

5.3 单节点故障测试

将node3节点直接关机，模拟节点彻底故障：

bash 复制代码

# 在node3上执行
shutdown -h now

节点离线时间达到设定值后，系统会将该节点标记为不可用。如果剩余节点数量仍大于副本数，系统自动补足缺失的副本。在3节点3副本的集群中，剩余2个节点，副本数为3，剩余节点数量小于副本数，系统无法补足缺失的副本。此时集群可以继续提供读写服务，因为2个存活节点仍满足多数投票机制的要求。

节点恢复后，系统会将副本和leaseholder回迁到该节点，迁移期间数据查询和DML操作可能受影响，DDL操作可能会报错，生命周期会顺延至下一执行周期执行。

5.4 多节点故障的边界

如果两个或更多节点同时出现故障，由于剩余节点数小于或等于副本数，系统无法补足缺失的副本，可能导致部分数据无法访问，甚至出现集群无法使用的情况。

在3节点3副本的集群中，两个节点故障后，仅剩1个节点存活，无法满足多数投票机制，集群将无法继续提供服务。这也是为什么官方建议部署5节点集群以获得更好的容错能力。

5.5 副本自动补足的控制

用户可以通过SQL命令调整不可用节点的判定时间：

sql 复制代码

SET CLUSTER SETTING server.time_until_store_dead = <value>;

默认情况下，节点离线超过30分钟会被标记为不可用节点，触发数据副本补足机制。设置时间建议不小于75秒。延长节点判定时间可以减少节点故障对集群性能的长时间影响，但可能会影响集群的高可用性功能和DDL相关操作。

用户也可以通过以下命令关闭自动补足副本功能：

sql 复制代码

SET CLUSTER SETTING kv.allocator.ts_store_dead_rebalance.enabled = false;

注意：在5节点三副本集群中禁用该功能后，将无法承受连续的节点故障。

六、部署后的运维要点

6.1 安全模式配置

KWDB支持安全模式和非安全模式部署。安全模式使用TLS加密技术验证节点和客户端的身份，并对节点与客户端之间的数据传输进行加密。非安全模式存在严重的安全风险：集群对所有客户端开放，所有用户无需密码即可访问，所有用户都可以以root身份访问集群并对所有数据进行读写操作。

生产环境强烈建议采用安全模式部署。安全模式的相关参数在部署时配置，secure_mode默认为tls，生成的客户端相关证书存放在/etc/kaiwudb/certs目录。

6.2 CPU资源占用率配置

KWDB支持限制服务占用的CPU资源比例。配置方法为修改/etc/systemd/system/kaiwudb.service文件中的CPUQuota参数：

复制代码

CPUQuota=180%

CPUQuota的计算公式为：CPU占用率乘以服务器CPU核数乘以100%。例如，假设节点所在服务器的CPU核数为6，计划将CPU占用率调整为0.3，则CPUQuota的值应为0.3×6×100%=180%。

注意：如果部署环境为Ubuntu 18.04版本，部署集群后需要将kaiwudb.service文件中的CPUQuota修改为整型值，例如将180.0%修改为180%，以确保设置生效。

6.3 用户创建与权限管理

KWDB安装包中提供了add_user.sh脚本，用于为数据库创建用户和密码：

bash 复制代码

./add_user.sh

根据系统提示输入用户名和密码即可创建。创建用户后，可以使用该用户名和密码连接数据库。

如需进行更精细的权限管理，可以使用SQL命令创建角色并授予权限：

sql 复制代码

CREATE ROLE analyst WITH LOGIN PASSWORD 'secure123';
GRANT SELECT ON TABLE sales TO analyst;
REVOKE DELETE ON ALL TABLES IN SCHEMA public FROM PUBLIC;

6.4 集群监控配置

KWDB提供了完整的监控方案，基于Prometheus和Grafana构建。部署Prometheus时，需要创建rules目录，放入KWDB提供的alerts.rules.yml和aggregation.rules.yml规则文件，并在prometheus.yml中配置scrape_configs以采集各节点的监控数据。

Grafana默认运行于3000端口，接入KWDB时需在Data Sources中添加Prometheus数据源。KWDB在monitoring/grafana-dashboards目录提供了九个面板JSON文件，涵盖概览、硬件、运行时等维度，通过Dashboard Import功能上传JSON即可一键生成视图。

关键监控指标包括SQL Queries QPS、Replicas per Node、Service Latency 99th百分位和Capacity使用比例。副本数量图帮助判断数据均衡性，若副本分布不均可能导致热点问题。

结语

KWDB多副本集群的部署，核心在于环境准备、SSH免密配置和集群初始化三个关键环节。硬件规划需要预留足够的CPU和内存资源，时钟同步是保证数据一致性的前提条件，SSH免密登录是部署脚本正常工作的基础。

多副本集群的高可用能力通过3副本机制和多数投票协议实现。单个节点故障时，系统自动迁移leaseholder并补足副本，数据查询和DML操作不受影响。但多节点同时故障时，集群将无法提供服务，因此生产环境建议部署5节点集群以获得更好的容错能力。

部署完成后的运维同样重要。安全模式配置保护数据传输安全，CPU资源占用率限制防止资源争抢，监控体系使集群运行状态透明可见。当这些基础工作到位后，KWDB多副本集群就能为AIoT场景提供稳定、可靠的数据服务。