【KWDB创作者计划】_KaiwuDB 2.1.0 单节点裸机部署

大家好，这里是 DBA学习之路，专注于提升数据库运维效率。

前言

今天无意间在墨天轮看到一个征文活动 征文大赛 |「码」上数据库—— KWDB 2025 创作者计划启动，想着参与一下支持开源，顺便了解一下新的开源时序数据库 KWDB。

写了一篇时序数据库 KWDB 的简单安装和使用，分享给大家一起看看~

KWDB 介绍

KWDB（KaiwuDB）是一款开源的时序数据库，是浪潮集团控股的数据库企业，以多模数据库为核心，主要面向工业物联网、数字能源、交通车联网、智慧城市、数字政务等多种场景。

早在 2023.01.10 KWDB 1.0 就已经正式发布，经过一年多的孵化，目前最新版已经来到 2.1.0，可以说已经是一款比较成熟的数据库了。

KWDB 为不同角色开发者提供以下支持（包括但不限于）：

为开发者提供通用连接接口，具备高速写入、极速查询、SQL 支持、随需压缩、数据生命周期管理、集群部署等特性，与第三方工具无缝集成，降低开发及学习难度，提升开发使用效率。
为运维管理人员提供快速安装部署、升级、迁移、监控等能力，降低数据库运维管理成本。

KWDB 官方资源参考：

KWDB 开源地址：https://gitee.com/kwdb/kwdb
部署操作文档：https://www.kaiwudb.com/kaiwudb_docs/#/oss_v2.1.0/quickstart/overview.html
KWDB 最新发行版 2.1.0 下载地址：https://gitee.com/kwdb/kwdb/releases/tag/V2.1.0

KWDB 支持用户根据需求选择二进制安装包、容器和源码安装与试用 KWDB 数据库：

二进制安装包：支持单机和集群以及安全和非安全部署模式。
源码安装：源码编译目前支持单节点非安全模式部署。
容器镜像：KWDB 暂未提供可供下载的容器镜像，如需以容器方式部署 KWDB，需要联系 KWDB 技术支持人员。

可以看到二进制安装包的方式支持的架构比较多，所以本文选择用二进制安装的方式进行部署。

安装准备

本文介绍如何使用 KWDB 二进制安装包在单个节点上安装部署 KWDB。

环境信息

这里本着国产数据库用国产系统，所以选择麒麟 V10 系统进行测试：

主机名	版本	CPU	内存	硬盘
kwdb	银河麒麟V10	x86	8G	100G

配置要求

参考官方手册给出的部署 KWDB 所需的硬件规格：

项目	要求
CPU 和内存	单节点配置建议不低于 4 核 8G。对于数据量大、复杂的工作负载、高并发和高性能场景，建议配置更高的 CPU 和内存资源以确保系统的高效运行。
磁盘	1、推荐使用 SSD 或者 NVMe 设备，尽量避免使用 NFS、CIFS、CEPH 等共享存储。 2、磁盘必须能够实现 500 IOPS 和 30 MB/s 处理效率。
文件系统	建议使用 ext4 文件系统。

实际部署时，用户可以根据实际的业务规模和性能要求规划硬件资源。

操作系统

KWDB 官方已经认证的服务器操作系统：

操作系统	版本	架构
Anolis	8.6	ARM_64
Anolis	8.6	x86_64
KylinOS	V10 SP3 2403 V10 SP3 2303	ARM_64
KylinOS	V10 SP3 2403 V10 SP3 2303	x86_64
Ubuntu	V20.04	ARM_64
Ubuntu	V20.04	x86_64
Ubuntu	V22.04	ARM_64
Ubuntu	V22.04	x86_64
Ubuntu	V24.04	ARM_64
Ubuntu	V24.04	x86_64
UOS	1060e	x86_64
UOS	1060e	ARM_64

软件依赖

KWDB 在安装时会对依赖进行检查，如果缺少依赖会退出安装并提示依赖缺失。不同操作系统及安装包的依赖略有不同，需要根据实际安装包类型及操作系统，在部署前安装好相应的依赖。

下表列出需要在目标机器安装的依赖：

依赖	版本	说明
OpenSSL	v1.1.1+	N/A
Protobuf	v3.5.0+	N/A
GEOS	v3.3.8+	可选依赖
xz-libs	v5.2.0+	N/A
squashfs-tools	any	N/A
libgcc	v7.3.0+	N/A
mount	any	N/A
squashfuse	any	可选依赖

配置本地软件源：

## 挂载本地镜像源
[root@kwdb ~]# mount /dev/cdrom /mnt/
mount: /mnt: WARNING: source write-protected, mounted read-only.
## 备份系统初始配置文件
[root@kwdb ~]# mkdir -p /etc/yum.repos.d/bak
[root@kwdb ~]# mv /etc/yum.repos.d/* /etc/yum.repos.d/bak
## 一键配置软件源，默认 ISO 安装镜像挂载在 /mnt 目录下
[root@kwdb ~]# cat<<-EOF>/etc/yum.repos.d/local.repo
[server]
name=server
baseurl=file:///mnt
enabled=1
gpgcheck=0
EOF

手动安装依赖：

yum install -y protobuf
## 手动下载上传
rpm -ivh geos-3.6.1-12.ky10.x86_64.rpm

检查操作系统是否已安装对应依赖：

[root@kwdb soft]# rpm -q openssl protobuf geos xz-libs squashfs-tools libgcc util-linux
openssl-1.1.1f-31.p23.ky10.x86_64
protobuf-3.14.0-7.ky10.x86_64
geos-3.6.1-12.ky10.x86_64
xz-libs-5.2.5-3.ky10.x86_64
squashfs-tools-4.5-4.ky10.x86_64
libgcc-7.3.0-2020033101.58.p01.ky10.x86_64
util-linux-2.35.2-14.p03.ky10.x86_64

确保所有的依赖都已成功安装。

端口要求

在安装部署前，确保目标机器的以下端口没有被占用且没有被防火墙拦截。在安装部署时，用户可以修改 deploy.cfg 文件中的端口配置参数。

下表列出 KWDB 服务需要映射的端口：

端口号	说明
8080	数据库 Web 服务端口
26257	数据库服务端口、节点监听端口和对外连接端口

建议关闭防火墙：

[root@kwdb ~]# systemctl stop firewalld.service 
[root@kwdb ~]# systemctl disable firewalld.service 
Removed /etc/systemd/system/multi-user.target.wants/firewalld.service.
Removed /etc/systemd/system/dbus-org.fedoraproject.FirewallD1.service.

安装包下载

在 gitee 上下载对应的二进制安装包：

将安装包复制到待安装 KWDB 的目标机器上，然后解压缩安装包：

[root@kwdb soft]# ll
总用量 27956
-rw-r--r-- 1 root root 28625639  3月 18 13:35 KWDB-2.1.0-kylinV10_2403-x86_64-rpms.tar.gz
[root@kwdb soft]# tar -xf KWDB-2.1.0-kylinV10_2403-x86_64-rpms.tar.gz 
[root@kwdb soft]# cd kwdb_install/

解压后生成的目录包含以下文件：

[root@kwdb kwdb_install]# tree -N
.
├── add_user.sh ## 安装、启动 KWDB 后，为 KWDB 数据库创建用户
├── deploy.cfg ## 安装部署配置文件，用于配置部署节点的 IP 地址、端口等配置信息
├── deploy.sh ## 安装部署脚本，用于安装、卸载、启动、状态获取、关停和重启等操作
├── packages ## 存放 DEB、RPM 和镜像包
│   ├── kwdb-libcommon-2.1.0-kylin.ky10.x86_64.rpm
│   └── kwdb-server-2.1.0-kylin.ky10.x86_64.rpm
└── utils ## 存放工具类脚本├── container_shell.sh├── kaiwudb_cluster.sh├── kaiwudb_common.sh├── kaiwudb_hardware.sh├── kaiwudb_install.sh├── kaiwudb_log.sh├── kaiwudb_operate.sh├── kaiwudb_uninstall.sh├── kaiwudb_upgrade.sh├── process_bar.sh└── utils.sh2 directories, 16 files

至此，环境准备完成，接下来可以开始部署 KWDB。

部署 KWDB

部署 KWDB 时，系统将对配置文件、运行环境、硬件配置和软件依赖进行检查。

如果相应硬件未能满足要求，系统将继续安装，并提示硬件规格不满足要求。
如果软件依赖未能满足要求，系统将中止安装，并提供相应的提示信息。

在部署过程中，系统会自动生成相关日志。如果部署时出现错误，用户可以通过查看终端输出或 KWDB 安装目录中 log 目录里的日志文件，获取详细的错误信息。

部署完成后，系统会将 KWDB 封装成系统服务（名称为 kaiwudb），并生成以下文件：

kaiwudb.service：配置 KWDB 的 CPU 资源占用率。
kaiwudb_env：配置 KWDB 启动参数。

安装用户为 root 用户或者拥有 sudo 权限的普通用户。

登录待部署节点，编辑安装包目录下的 deploy.cfg 配置文件，设置安全模式、管理用户、服务端口等信息：

## 默认情况下，deploy.cfg 配置文件中包含集群配置参数，需要删除或注释 [cluster] 集群配置项。
[root@kwdb kwdb_install]# cat<<-EOF>/soft/kwdb_install/deploy.cfg
[global]
secure_mode=insecure
management_user=kaiwudb
rest_port=8080
kaiwudb_port=26257
data_root=/var/lib/kaiwudb
cpu=1
[local]
node_addr=192.168.6.79
EOF

参数说明：

global：全局配置
- secure_mode：是否开启安全模式，支持以下两种取值：
  - insecure：使用非安全模式。
  - tls：（默认选项）开启 TLS 安全模式。开启安全模式后，KaiwuDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证，生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
- management_user：KaiwuDB 的管理用户，默认为 kaiwudb。安装部署后，KaiwuDB 创建相应的管理用户以及和管理用户同名的用户组。
- rest_port：KaiwuDB Web 服务端口，默认为 8080。
- kaiwudb_port：KaiwuDB 服务端口，默认为 26257。
- data_root：数据目录，默认为 /var/lib/kaiwudb。
- cpu: 可选参数，用于指定 KaiwuDB 服务占用当前节点服务器 CPU 资源的比例，默认无限制。取值范围为 [0,1]，最大精度为小数点后两位。
local：本地节点配置
- node_addr：本地节点对外提供服务的 IP 地址，监听地址为 0.0.0.0，端口为 KaiwuDB 服务端口。

为 deploy.sh 脚本添加运行权限：

[root@kwdb kwdb_install]# chmod +x deploy.sh

安装过程中需要输入 kaiwudb 用户密码，复杂度参考操作系统，不符合复杂度会报错退出安装。如果没有密码复杂性要求，不想设置密码太复杂的话，可以取消密码复杂度：

[root@kwdb kwdb_install]# sed -i 's/^password\+[[:space:]]\+requisite[[:space:]]\+pam_pwquality.so/#&/g' /etc/pam.d/system-auth
[root@kwdb kwdb_install]# sed -i 's/use_authtok$//' /etc/pam.d/system-auth

执行单机部署安装命令：

[root@kwdb kwdb_install]# ./deploy.sh install --single
## 这里需要输入 kaiwudb 用户的密码，输完之后记得保留密码

执行成功后，控制台输出以下信息：

[INSTALL COMPLETED]:KaiwuDB has been installed successfully! To start KaiwuDB, please execute the command 'systemctl daemon-reload'.

根据系统提示重新加载 systemd 守护进程的配置文件：

[root@kwdb kwdb_install]# systemctl daemon-reload

启动 KWDB 节点：

[root@kwdb kwdb_install]# ./deploy.sh start
[START COMPLETED]:KaiwuDB start successfully.

执行成功后，控制台输出以上信息。

查看 KWDB 节点状态：

[root@kwdb kwdb_install]# ./deploy.sh status
[STATUS COMPLETED]:KaiwuDB is runnning now.[root@kwdb kwdb_install]# systemctl status kaiwudb
● kaiwudb.service - KaiwuDB ServiceLoaded: loaded (/etc/systemd/system/kaiwudb.service; disabled; vendor preset: disabled)Active: active (running) since Tue 2025-03-18 14:21:11 CST; 49s agoProcess: 40587 ExecStartPre=/usr/bin/sudo /usr/sbin/sysctl -w vm.max_map_count=10000000 (code=exited, status=0/SUCCESS)Main PID: 40598 (kwbase)Tasks: 41Memory: 477.1MCGroup: /system.slice/kaiwudb.service└─40598 /usr/local/kaiwudb/bin/kwbase start-single-node --insecure --listen-addr=0.0.0.0:26257 --advertise-addr=192.168.6.79:26257 --http-addr=0.0.0.0:8080 --store=/var/lib/kaiwudb3月 18 14:21:13 kwdb kwbase[40598]: sql:                 postgresql://root@192.168.6.79:26257?sslmode=disable
3月 18 14:21:13 kwdb kwbase[40598]: RPC client flags:    /usr/local/kaiwudb/bin/kwbase <client cmd> --host=192.168.6.79:26257 --insecure
3月 18 14:21:13 kwdb kwbase[40598]: logs:                /var/lib/kaiwudb/logs
3月 18 14:21:13 kwdb kwbase[40598]: temp dir:            /var/lib/kaiwudb/kwbase-temp492528165
3月 18 14:21:13 kwdb kwbase[40598]: external I/O path:   /var/lib/kaiwudb/extern
3月 18 14:21:13 kwdb kwbase[40598]: store[0]:            path=/var/lib/kaiwudb
3月 18 14:21:13 kwdb kwbase[40598]: storage engine:      rocksdb
3月 18 14:21:13 kwdb kwbase[40598]: status:              initialized new cluster
3月 18 14:21:13 kwdb kwbase[40598]: clusterID:           532f74b0-03a7-4921-839b-5132f10644cf
3月 18 14:21:13 kwdb kwbase[40598]: nodeID:              1

配置 KWDB 开机自启动：

[root@kwdb kwdb_install]# systemctl enable kaiwudb
Created symlink /etc/systemd/system/multi-user.target.wants/kaiwudb.service → /etc/systemd/system/kaiwudb.service.

配置 KWDB 开机自启动后，如果系统重启，则自动启动 KWDB。

简单实用

连接数据库

[kaiwudb@kwdb ~]$ kwbase sql --insecure --host=192.168.6.79
#
# Welcome to the KWDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
# Server version: KaiwuDB 2.1.0 (x86_64-linux-gnu, built 2024/11/22 12:14:25, go1.16.15, gcc 7.3.0) (same version as client)
# Cluster ID: 532f74b0-03a7-4921-839b-5132f10644cf
#
# Enter \? for a brief introduction.
#
root@192.168.6.79:26257/defaultdb> show database;database
-------------defaultdb
(1 row)Time: 795.282µs

创建数据库

-- 创建一个名称为 tsdb 的时序库，数据保存周期为 90 天
root@192.168.6.79:26257/defaultdb> CREATE TS DATABASE tsdb RETENTIONS 90d;
CREATE TS DATABASETime: 8.576464msroot@192.168.6.79:26257/defaultdb> SHOW DATABASES;database_name | engine_type
----------------+--------------defaultdb     | RELATIONALpostgres      | RELATIONALsystem        | RELATIONALtsdb          | TIME SERIES
(4 rows)Time: 1.913474msroot@192.168.6.79:26257/defaultdb> USE tsdb;SETTime: 1.011287ms

创建用户

-- 创建一个名称为 testu 的用户，授予其 tsdb 数据库的所有权限
CREATE USER testu;
GRANT ALL ON DATABASE tsdb to testu;
SHOW USERS;

创建时序表

在 tsdb 数据库中创建名为 readings 的时序表，存储温度和湿度数据，并使用传感器 ID 和位置作为标签：

root@192.168.6.79:26257/defaultdb> use tsdb;
SETTime: 990.008µsroot@192.168.6.79:26257/tsdb> CREATE TABLE tsdb.readings (ts timestamp NOT NULL,         -- 数据读取时间戳temperature FLOAT,             -- 温度（摄氏度）humidity FLOAT                 -- 湿度（百分比）
) TAGS (sensor_id INT NOT NULL,        -- 传感器 IDlocation CHAR(256) NOT NULL    -- 传感器位置（如 "Room 101"）
) PRIMARY TAGS(sensor_id);
CREATE TABLETime: 69.114769ms

向 readings 时序表中写入数据：

root@192.168.6.79:26257/tsdb> INSERT INTO tsdb.readings 
VALUES 
(NOW(), 23.0, 59.5, 101, 'Room 101'),
(NOW(), 23.5, 58.9, 102, 'Room 102'),
(NOW(), 19.8, 65.5, 103, 'Room 103');
INSERT 3Time: 18.171494ms

查询 readings 时序表中的数据：

root@192.168.6.79:26257/tsdb> SELECT * FROM readings;ts              | temperature | humidity | sensor_id | location
-------------------------------+-------------+----------+-----------+-----------2025-03-18 07:13:53.75+00:00 |          23 |     59.5 |       101 | Room 1012025-03-18 07:13:53.75+00:00 |        23.5 |     58.9 |       102 | Room 1022025-03-18 07:13:53.75+00:00 |        19.8 |     65.5 |       103 | Room 103
(3 rows)Time: 2.194378ms

查看已创建的表结构：

root@192.168.6.79:26257/tsdb> SHOW CREATE TABLE readings;table_name |                     create_statement
-------------+------------------------------------------------------------readings   | CREATE TABLE readings (|     ts TIMESTAMPTZ NOT NULL,|     temperature FLOAT8 NULL,|     humidity FLOAT8 NULL| ) TAGS (|     sensor_id INT4 NOT NULL,|     location CHAR(256) NOT NULL ) PRIMARY TAGS(sensor_id)
(1 row)Time: 236.503887ms