原文链接：【KWDB创作者计划】_KaiwuDB 2.1.0 单节点裸机部署 - 墨天轮

作者：Lucifer三思而后行

一、前言

今天无意间在墨天轮看到一个征文活动 征文大赛 |「码」上数据库—— 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。

3.1 环境信息

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

3.2 配置要求

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

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

3.3 操作系统

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

3.4 软件依赖

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

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

配置本地软件源：

## 挂载本地镜像源[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-linuxopenssl-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

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

3.5 端口要求

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

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

建议关闭防火墙：

[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.

3.6 安装包下载

在 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.sh

2 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：全局配置

• insecure：使用非安全模式。
• tls：（默认选项）开启 TLS 安全模式。开启安全模式后，KaiwuDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证，生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
• secure_mode：是否开启安全模式，支持以下两种取值：
• 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 Service
   Loaded: loaded (/etc/systemd/system/kaiwudb.service; disabled; vendor preset: disabled)
   Active: active (running) since Tue 2025-03-18 14:21:11 CST; 49s ago
  Process: 40587 ExecStartPre=/usr/bin/sudo /usr/sbin/sysctl -w vm.max_map_count=10000000 (code=exited, status=0/SUCCESS)
 Main PID: 40598 (kwbase)
    Tasks: 41
   Memory: 477.1M
   CGroup: /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/kaiwudb

3月 18 14:21:13 kwdb kwbase[40598]: sql:                 postgresql://root@192.168.6.79:26257?sslmode=disable3月 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 kaiwudbCreated symlink /etc/systemd/system/multi-user.target.wants/kaiwudb.service → /etc/systemd/system/kaiwudb.service.

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

五、简单实用

5.1 连接数据库

[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

5.2 创建数据库

-- 创建一个名称为 tsdb 的时序库，数据保存周期为 90 天root@192.168.6.79:26257/defaultdb> CREATE TS DATABASE tsdb RETENTIONS 90d;CREATE TS DATABASETime: 8.576464ms

root@192.168.6.79:26257/defaultdb> SHOW DATABASES;
  database_name | engine_type----------------+--------------
  defaultdb     | RELATIONAL
  postgres      | RELATIONAL
  system        | RELATIONAL
  tsdb          | TIME SERIES
(4 rows)

Time: 1.913474ms

root@192.168.6.79:26257/defaultdb> USE tsdb;SETTime: 1.011287ms

5.3 创建用户

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

5.4 创建时序表

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

root@192.168.6.79:26257/defaultdb> use tsdb;SETTime: 990.008µs

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

向 readings 时序表中写入数据：

root@192.168.6.79:26257/tsdb> ｉｎｓｅｒｔ 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');ｉｎｓｅｒｔ 3Time: 18.171494ms

查询 readings 时序表中的数据：

root@192.168.6.79:26257/tsdb> ｓｅｌｅｃｔ * FROM readings;
               ts              | temperature | humidity | sensor_id | location-------------------------------+-------------+----------+-----------+-----------
  2025-03-18 07:13:53.75+00:00 |          23 |     59.5 |       101 | Room 101
  2025-03-18 07:13:53.75+00:00 |        23.5 |     58.9 |       102 | Room 102
  2025-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 ｃｈａｒ(256) NOT NULL ) PRIMARY TAGS(sensor_id)
(1 row)Time: 236.503887ms复制

到这， KaiwuDB 的单机安装就完成了。