KWDB创作者计划—KWDB多副本集群保姆级部署
📢📢📢📣📣📣
作者：IT邦德
中国DBA联盟(ACDU)成员，10余年DBA工作经验
Oracle、PostgreSQL ACE
CSDN博客专家及B站知名UP主，全网粉丝10万+
擅长主流Oracle、MySQL、PG、高斯及Greenplum备份恢复，
安装迁移，性能优化、故障应急处理
文章目录
- 1.部署概述
- 2.安装包
- 3.节点配置
- 3.1 SSH 免密登录
- 3.2 时钟同步
- 4.裸机部署
- 5.初始化并启动集群
- 6.配置集群
- 7.集群的日常运维
- 7.1 创建用户
- 7.2 集群启动
- 7.3 分片
KWDB作为一款分布式数据库，其集群管理涉及架构设计、部署、监控、调优和故障处理等多个方面。以下从关键管理维度进行详细说明，帮助您高效运维 KaiwuDB 集群
1.部署概述
KWDB 支持使用容器或二进制安装包部署以下集群：
2.安装包
获取系统环境对应的 DEB 或 RPM 安装包，将安装包复制到待安装 KWDB 的目标机器上，然后解压缩安装包：
1.所需资源包下载地址：
https://gitee.com/kwdb/kwdb/releases/tag/V2.2.0
tar -xzvf KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz
root@jeames-virtual-machine:/opt# cd kwdb_install/
root@jeames-virtual-machine:/opt/kwdb_install# ll
total 52
drwxr-xr-x 4 root root 4096 3月 31 15:22 ./
drwxr-xr-x 3 root root 4096 4月 11 23:11 …/
-rwxr-xr-x 1 root root 2024 3月 31 15:11 add_user.sh*
-rw-r–r-- 1 root root 3605 3月 31 15:12 .construction_var
-rw-r–r-- 1 root root 465 3月 31 15:11 deploy.cfg
-rwxr-xr-x 1 root root 24410 3月 31 15:11 deploy.sh*
drwxr-xr-x 2 root root 4096 3月 31 15:22 packages/
drwxr-xr-x 2 root root 4096 3月 31 15:11 utils/
2.相关依赖安装
sudo apt update
sudo apt install cmake
sudo snap install go --classic
sudo apt install libprotobuf-dev
3.节点配置
3.1 SSH 免密登录
登录当前节点，生成公私密钥对,每个节点均操作
ssh-keygen -f ~/.ssh/id_rsa -N “”
参数说明：
-f：指定生成的密钥对文件名。
-N：指定使用密钥时的密码。为了实现非交互式登录，建议将密码设置为空。
将密钥分发至集群其它节点。
sudo hostnamectl set-hostname node1
sudo hostnamectl set-hostname node2
sudo hostnamectl set-hostname node3
vi /etc/hosts
192.168.3.10 node1
192.168.3.11 node2
192.168.3.12 node3
root@jeames-virtual-machine:~# hostnamectl
Static hostname: node1
Icon name: computer-vm
Chassis: vm
Machine ID: ba13b266fdb04c3c9fc7d06c4e7fa8ea
Boot ID: 793ca8918e984d9f84cf718ca4ce03c8
Virtualization: vmware
Operating System: Ubuntu 22.04.5 LTS
Kernel: Linux 6.8.0-57-generic
Architecture: x86-64
Hardware Vendor: VMware, Inc.
Hardware Model: VMware Virtual Platform
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
确认是否可以使用非交互式的方法登录集群其它节点
ssh node1
ssh node2
ssh node3
3.2 时钟同步
KWDB 采用中等强度的时钟同步机制来维持数据的一致性。当节点检测到自身的机器时间与集群中至少 50% 的节点的机器时间的误差值超过集群最大允许时间误差值（默认为 500 ms）的 80% 时，该节点会自动停止，从而避免违反数据一致性，带来读写旧数据的风险。每个节点都必须运行 NTP（Network Time Protocol，网络时间协议）或其他时钟同步软件，防止时钟漂移得太远。
启用 NTP 服务
sudo timedatectl set-ntp on
sudo apt update && sudo apt install ntp
timedatectl status
2.重启服务
sudo systemctl restart ntp
sudo ntpq -p
4.裸机部署
登录待部署节点，编辑安装包目录下的 deploy.cfg 配置文件，设置安全模式、管理用户、服务端口等信息，并添加其他节点信息。
cd /opt/kwdb_install
vi deploy.cfg
[global]
# Whether to turn on secure mode
secure_mode=tls
# Management KaiwuDB user
management_user=kaiwudb
# KaiwuDB cluster http port
rest_port=8080
# KaiwuDB service port
kaiwudb_port=26257
# KaiwuDB data directory
data_root=/var/lib/kaiwudb
# CPU usage[0-1]
# cpu=1
[local]
# local node configuration
node_addr=192.168.3.10
# section cluster is optional
[cluster]
# remote node addr,split by ','
node_addr=192.168.3.10,192.168.3.11,192.168.3.12
# ssh info
ssh_port=22
ssh_user=root
配置参数说明：
global：全局配置
secure_mode：是否开启安全模式，支持以下两种设置：
insecure：使用非安全模式。
tls：（默认选项）开启 TLS 安全模式。开启安全模式后，KWDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
management_user：KWDB 的管理用户，默认为 kaiwudb。安装部署后，KWDB 创建相应的管理用户以及和管理用户同名的用户组。
rest_port：KWDB Web 服务端口，默认为 8080。
kaiwudb_port：KWDB 服务端口，默认为 26257。
data_root：数据目录，默认为 /var/lib/kaiwudb。
cpu: 可选参数，用于指定 KWDB 服务占用当前节点服务器 CPU 资源的比例，默认无限制。取值范围为 [0,1]，最大精度为小数点后两位。KWDB 支持调整 CPU 资源占用率。更多信息，参见配置集群。注意：如果部署环境为 Ubuntu 18.04 版本，部署集群后，需要将 kaiwudb.service 文件中的 CPUQuota 修改为整型值，例如，将 180.0% 修改为 180%，以确保设置生效。具体操作步骤，参见配置 CPU 资源占用率。
local：本地节点配置
local_node_ip：本地节点对外提供服务的 IP 地址，监听地址为 0.0.0.0，端口为 KWDB 服务端口。
cluster：集群内其他节点的配置
cluster_node_ips：远程节点对外提供服务的 IP 地址。各节点的 IP 地址使用逗号（,）分割，远程节点数应不少于 2 个。
ssh_port：远程节点的 SSH 服务端口。各节点的 SSH 服务端口必须相同。
ssh_user：远程节点的 SSH 登录用户。各节点的 SSH 登录用户必须相同
为 deploy.sh 脚本增加运行权限
chmod +x ./deploy.sh
执行安装命令
多副本集群
./deploy.sh install --multi-replica
多副本架构：每个数据分片配置 3 副本（1 Leader + 2 Followers），通过 Raft/Paxos 协议保证数据一致性
单副本集群
./deploy.sh install --single-replica
输入密码：beijing
root@node1:/opt/kwdb_install# ./deploy.sh install --multi-replica
[WARN] 2025-04-12 00:07:55 The number of CPU cores does not meet the requirement. KaiwuDB may running failed.
The authenticity of host '192.168.3.12 (192.168.3.12)' can't be established. ] 20%
ED25519 key fingerprint is SHA256:edOHleuRe8EgN1wyHQFPQxs5T1Uj9trdIGQgBGsGcTs.
This host key is known by the following other names/addresses:
~/.ssh/known_hosts:1: [hashed name]
~/.ssh/known_hosts:4: [hashed name]
~/.ssh/known_hosts:5: [hashed name]
~/.ssh/known_hosts:6: [hashed name]
~/.ssh/known_hosts:7: [hashed name]
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Please input kaiwudb's password: [INSTALL COMPLETED]:KaiwuDB has been installed successfully! To start KaiwuDB, please execute the command 'systemctl daemon-reload'.
、
根据系统提示重新加载 systemd 守护进程的配置文件
systemctl daemon-reload
5.初始化并启动集群
集群初始化和启动大约需要 10 秒左右时间。在此期间，如果有节点死亡，可能会导致集群无法触发高可用机制。
./deploy.sh cluster -i
root@node1:/opt/kwdb_install# ./deploy.sh cluster -i
[INIT COMPLETED]:Cluster init successfully.
查看集群节点状态
./deploy.sh cluster -s
./deploy.sh cluster --status
配置 KWDB 开机自启动
配置 KWDB 开机自启动后，如果系统重启，则自动启动 KWDB。
systemctl enable kaiwudb
systemctl status kaiwudb
6.配置集群
部署完 KWDB 集群以后，用户可以按需配置 KWDB 集群。本文介绍如何配置通过二进制安装包部署的 KWDB 集群。
部署完成后，系统会将 KWDB 封装成系统服务，并生成 kaiwudb.service 和 kaiwudb_env 两个文件。用户可以按需配置 KWDB 集群。
kaiwudb_env：配置 KWDB 启动参数
kaiwudb.service：配置 KWDB 的 CPU 资源占用率
启动参数是节点级配置。如需修改整个集群的配置，用户需要登录集群中的每个节点并完成相应的配置。
1.停止 KWDB 服务
systemctl stop kaiwudb
2.进入 /etc/kaiwudb/script 目录，打开 kaiwudb_env 文件。
3.根据需要，配置 KWDB 启动参数。
以下示例将 --cache 启动参数设置为 10000
KAIWUDB_START_ARG=“–cache=10000”
4.保存 kaiwudb_env 文件并重新加载文件。
systemctl daemon-reload
5.重新启动 KWDB 服务
systemctl restart kaiwudb
CPU 资源占用率是节点级配置。如需修改整个集群的配置，用户需要登录集群中的每个节点并完成相应的配置。
1.进入 /etc/systemd/system 目录，打开 kaiwudb.service 文件。
2.根据需要，修改 KWDB 的 CPU 资源占用率。
以下示例将 CPU 资源占用率（CPUQuota）设置为 180%。
CPUQuota=180%
CPUQuota 的计算公式为：CPU 占用率 x 服务器CPU核数 x 100%。例如，假设节点所在服务器的 CPU 核数为 6，计划将 CPU 占用率调整为 0.3, 则对应的 CPUQuota 的值应为 0.3 x 6 x 100% = 180%。
保存 kaiwudb.service 文件并重新加载文件。
systemctl daemon-reload
确认新的 CPU 资源占用率是否生效。
7.集群的日常运维
7.1 创建用户
KWDB 在安装包中提供了 add_user.sh 脚本。在安装并运行 KWDB 后，用户可以运行此脚本为数据库创建用户和密码，并使用创建的用户名和密码来连接、登录数据库。
1.在目标机器上，进入 KWDB 安装包目录。
2.执行 add_user.sh 脚本，根据系统提示创建用户名和密码。
./add_user.sh
Please enter the username:test
Please enter the password:beijing
– 创建角色并限制访问
CREATE ROLE analyst WITH LOGIN PASSWORD ‘secure123’;
GRANT SELECT ON TABLE sales TO analyst;
REVOKE DELETE ON ALL TABLES IN SCHEMA public FROM PUBLIC;
7.2 集群启动
systemctl status kaiwudb # 查看服务状态
systemctl restart kaiwudb # 滚动重启单个节点（需逐个操作）
systemctl enable kaiwudb # 设置开机自启
sudo apt-get install postgresql-client
root@node1:/opt/kwdb_install# psql -U test -h 127.0.0.1 -p 26257
Password for user test:
psql (14.17 (Ubuntu 14.17-0ubuntu0.22.04.1), server 9.5.0)
SSL connection (protocol: TLSv1.2, cipher: ECDHE-RSA-AES128-GCM-SHA256, bits: 128, compression: off)
Type "help" for help.
test=> use defaultdb;
SET
test=> SHOW DATABASES WITH COMMENT;
database_name | engine_type | comment
---------------+-------------+---------
defaultdb | RELATIONAL |
postgres | RELATIONAL |
system | RELATIONAL |
test=> show users;
username | options | member_of
----------+------------+-----------
admin | CREATEROLE | {}
root | CREATEROLE | {admin}
test | | {admin}
test=> show SERVER_VERSION;
server_version
----------------
9.5.0
7.3 分片
KWDB 多副本集群默认采用 3 副本机制。为了确保系统在节点发生故障后仍能够提供服务，集群通过多数投票机制保证数据一致性和可用性，因此至少需要 2 个副本保持可用状态。
正常运行：KWDB 集群启动后，副本和 leaseholder 均匀分布在所有节点上，确保数据的高可用性和平衡性。
单节点异常：如果单个节点因网络断开、延迟、操作系统故障、磁盘故障等原因导致节点状态变为异常（is_available 和 is_live 均为 false），系统会开始迁移该节点的 leaseholder，迁移期间数据查询和 DML 操作可能受影响，DDL 操作可能会报错，生命周期会顺延至下一执行周期执行。待节点恢复为可用状态后恢复正常。
单节点故障：节点离线时间达到设定值后，系统会将该节点标记为不可用。如果剩余节点数量仍大于副本数，系统自动补足缺失的副本，确保数据的高可用性、副本补足期间，数据查询不受影响，DML 操作不受影响，DDL 操作可能会报错，副本补足后，DDL 操作恢复正常。
节点恢复：不可用节点恢复后，系统会将副本和 leaseholder 回迁到该节点，迁移期间数据查询和 DML 操作可能受影响，DDL 操作可能会报错，生命周期会顺延至下一执行周期执行。待节点恢复为可用状态后恢复正常。
多节点故障：如果两个或更多节点出现故障，由于剩余节点数小于或等于副本数，系统无法补足缺失的副本，可能导致部分数据无法访问，甚至出现集群无法使用的情况。
节点故障影响：
集群节点多次发生故障后重新加入，可能会导致数据写入缓慢。
集群节点故障或故障节点恢复后的 leaseholder 迁移可能导致读写短暂不可用或卡顿。
可通过重试机制解决因 update tag 失败导致不同节点查询普通标签时的不一致问题。