原文链接：10分钟快速搞定 KWDB 数据库单节点部署 - 墨天轮

作者：jiayou

一、部署概要

KaiwuDB 是浪潮出品的一款面向 AIoT 场景的分布式、多模融合、支持原生 AI 的数据库产品，支持同一实例同时建立时序库和关系库并融合处理多模数据，具备时序数据高效处理能力，具有稳定安全、高可用、易运维等特点。面向工业物联网、数字能源、车联网、智慧产业等领域，KWDB 提供一站式数据存储、管理与分析的基座。长期位居时序数据库排名前二。

KWDB 是 KaiwuDB 的社区版，目前已更新到KWDB 2.2.0 版本。KWDB 2.2.0 版本在保持原有特性的基础上，针对时间精度、数据库对象、DML 操作、数据查询及数据库运维等方面进行了优化与增强。

KWDB 支持使用裸机或容器安装包部署单节点或集群。本文演示麒麟 KYLIN V10 SP3环境下单节点裸机部署KWDB 2.2.0。

二、部署前准备

2.1 软硬件环境要求

KWDB 支持在以下服务器操作系统进行安装部署。

硬件要求：

2.2 软件依赖

安装时，KWDB 会对依赖进行检查。如果缺少依赖会退出安装并提示依赖缺失。

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

2.3 端口要求

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

三、部署 KWDB

部署 KWDB 时，系统将对配置文件、运行环境、硬件配置和软件依赖进行检查。如果相应硬件未能满足要求，系统将继续安装，并提示硬件规格不满足要求。如果软件依赖未能满足要求，系统将中止安装，并提供相应的提示信息。

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

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

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

3.1 下载安装介质并解压

本文档采用下载二进制最新版 KWDB 2.2.0介质进行安装。

Gitee 社区下载地址：https://gitee.com/kwdb/kwdb

也可以通过官网社区下载：https://www.kaiwudb.com/community/

首先将获取系统环境对应的 DEB 或 RPM 安装包复制到待安装 KWDB 的目标机器上，然后解压缩安装包:

tar -zxvf KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz

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

3.2 执行安装

3.2.1 修改安装配置文件deploy.cfg

编辑安装包目录下的 deploy.cfg 配置文件，设置安全模式、管理用户、服务端口等信息。默认情况下，deploy.cfg 配置文件中包含集群配置参数。请删除或注释 [cluster] 集群配置项。

vi deploy.cfg

[global] // 全局配置

secure_mode=tls // 是否开启安全模式，默认开启TLS安全模式。开启安全模式后，KaiwuDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。

management_user= kaiwudb // kaiwudb 的管理用户，默认为 kaiwudb。安装部署后，KaiwuDB 创建相应的管理用户以及和管理用户同名的用户组。

rest_port=8080 // kaiwudb Web 服务端口，默认为 8080。

kaiwudb_port=26257 // kaiwudb 服务端口，默认为 26257

data_root=/var/lib/kaiwuDB // 数据目录，默认为 /var/lib/kaiwuDB

cpu=1 // 指定 KWDB 服务占用当前节点服务器 CPU 资源的比例，默认无限制。取值范围为[0,1]。最大精度为小数点后两位。

encrypto_store=true

[local] // 本地节点配置

node_addr=192.168.126.130

# [cluster] // 集群节点配置，本次单节点配置需要注释掉

# node_addr=your-host-ip, your-host-ip

# ssh_port=22

# ssh_user=admin

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

chmod +x ./deploy.sh

3.2.3 执行单机部署安装命令。

./deploy.sh install --single

注意：需要根据提示设置数据库密码。

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

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

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

systemctl daemon-reload

3.3 启动 KWDB 节点。

./deploy.sh start

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

START COMPLETED: KaiwuDB has started successfuly.

3.4 查看 KWDB 节点状态。

./deploy.sh status

[STATUS COMPLETED]: KaiwuDB is runnning now.

systemctl status kaiwudb

3.5 配置 KWDB 开机自启动（可选）

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

systemctl enable kaiwudb

Created symlink /etc/systemd/system/multi-user.target.wants/KWDB.service → /etc/systemd/system/KWDB.service.

# 删除KWDB开机自启动

sudo systemctl disable kaiwudb.service

Removed /etc/systemd/system/multi-user.target.wants/KWDB.service.

3.6 创建数据库用户

执行 add_user.sh 脚本创建数据库用户。如果跳过该步骤，系统将默认使用 root 用户，且无需密码访问数据库。

./add_user.sh

Please enter the username: kaiwudb

Please enter the password:

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

[ADD USER COMPLETED]:User creation completed.

四、访问 KWDB

用户可以采取以下任一方式连接 KWDB 服务端并进行 SQL 操作：

• 通过 kwbase CLI 工具连接和管理 KWDB
• 通过 KWDB Developer Center（KWDB 开发者中心）连接和管理 KWDB
• 通过 KWDB JDBC 连接和管理 KWDB

4.1 使用 kwbase CLI 工具连接 KWDB

kwbase 是 KWDB 提供的内置命令行工具。用户可以通过 kwbase 以安全模式（适用于生产环境）或非安全模式（适用于测试）连接 KWDB，进行数据库操作和维护。

# 用户连接 KWDB。不指定-u，默认root登录。

#非安全模式

kwbase sql --insecure --host= -u user1

#默认TLS安全模式

kwbase sql --host=192.168.126.130 -u kaiwudb --certs-dir=/etc/kaiwudb/certs

用户可以在任何 KWDB 客户端使用 \h 命令查看 KWDB 支持的所有 SQL 语句及相关描述。

也可以使用关键字查看某一类的 SQL 语句。

比如：使用 SHOW 关键字查看 KWDB 支持的所有 SHOW 语句

\h SHOW;

4.2 安装 KaiwuDB 开发者中心连接 KWDB

获取系统环境对应的 DEB 或 RPM 安装包，然后解压缩安装包，调用图形化界面连接数据库。

4.2.1 Linux系统：

tar -zxvf KaiwuDB_Developer_Center-2.0.4-linux-x86_64.tar.gz

cd KaiwuDB_Developer_Center-linux-x86_64/

export DISPLAY=192.168.126.1:0.0

./‘KaiwuDB Developer Center’

4.2.2 Win系统：

解压KaiwuDB_Developer_Center-2.0.4-win-x86_64.zip。

双击 KaiwuDB Developer Center.exe，创建新连接。

4.3 常用查询

数据库版本查看

ｓｅｌｅｃｔ version();

查看数据库用户

SHOW USERS 或 SHOW ROLES 语句用于查询数据库的用户信息。

查看数据库

show databases;

查看已创建数据库的注释信息

SHOW DATABASES WITH COMMENT;

查看数据库的建库语句

SHOW CREATE DATABASE <database_name>;

切换数据库

USE <database_name>;

查看模式

show schemas;

查看查询

SHOW QUERIES 语句用于获取 SQL 语句执行的进度信息。

查看会话

SHOW SESSIONS 语句用于查看当前正在进行的会话的详细信息，包括：

• 连接的目标节点
• 打开会话的客户端的地址
• 连接时长
• 会话中正在进行的查询
• 会话中运行时间最长的查询

查看集群内正在进行的会话。

SHOW ALL CLUSTER SESSIONS;

查看当前节点上正在进行的会话。

SHOW ALL LOCAL SESSIONS;

使用 ｓｅｌｅｃｔ 语句通过一个或多个返回字段查看特定会话。

ｓｅｌｅｃｔ * FROM [SHOW ALL CLUSTER SESSIONS] WHERE user_name = ‘root’;

取消会话

CANCEL SESSION 语句用于停止长时间运行的会话。

取消单个会话。

– 取消特定ID的会话：

CANCEL SESSION ‘session_id’;

取消多个会话。

CANCEL SESSIONS (ｓｅｌｅｃｔ session_id FROM [SHOW SESSIONS] WHERE user_name = ‘kaiwudb’);

五、KWDB 服务启动与停止

• 使用脚本启停

./deploy.sh stop

KaiwuDB stop successfully.

./deploy.sh start

[START COMPLETED]: KaiwuDB start successfully.

./deploy.sh status

[STATUS COMPLETED]: KaiwuDB is runnning now.

• 使用系统服务名KaiwuDB启停

systemctl start kaiwudb

systemctl status kaiwudb

systemctl stop kaiwudb

[STOP COMPLETED]: KaiwuDB stop successfully.

systemctl restart kaiwudb

六、卸载 KWDB

• 停止KWDB 服务

systemctl stop kaiwudb

• 删除与KWDB 服务相关的systemd 配置文件

sudo rm /etc/systemd/system/kaiwudb.service

• 删除 /etc/kaiwudb 目录及其内容

sudo rm -rf /etc/kaiwudb/

• 删除 KWDB 的数据目录及其内容 ，默认数据库目录为 /var/lib/kaiwudb

sudo rm -rf /var/lib/kaiwudb

• 卸载 KWDB 服务及相关的库

sudo apt-get -y remove kaiwudb-server kaiwudb-libcommon libopentelemetry-kaiwudb

• 删除 KWDB 管理用户及关联文件，管理用户默认为 kaiwudb

sudo userdel -r kaiwudb

七、问题整理

7.1 KaiwuDB 已安装无法启动问题

[ERROR] 2025-04-15 14:39:07 KaiwuDB is not runnning now.

[WARN] 2025-04-15 14:39:47 The number of CPU cores does not meet the requirement. KaiwuDB may running failed.

原因：单节点配置建议不低于 4 核 8G。本机配置低于4核配置引起，重新调整启动正常。

7.2 kwbase cli 工具登录问题

kwbase sql --host=192.168.126.130

ERROR: cannot load certificates.

Check your certificate settings, set --certs-dir, or use --insecure for insecure clusters.

problem with CA certificate: not found

Failed running “sql”

原因：安全模式连接需要添加–certs-dir参数

kwbase sql --host=192.168.126.130 --certs-dir=/etc/kaiwudb/certs

root@192.168.126.130:26257/defaultdb>

7.3 KaiwuDB开发者中心linux版本解压之后，可执行文件’KaiwuDB Developer Center’存在空格等问题，建议调整。

八、总结

KaiwuDB 2.2.0单节点部署非常简单，根据官方网站提供文档可以快速上手。单节点高可用方案以及集群方案，有时间在探索。KaiwuDB论坛已上线，感兴趣的伙伴可以登录学习https://www.kaiwudb.com/blog/632.html。

KWDB是KaiwuDB的社区版，再下载部署过程中存在包，路径等名称命名混淆的问题。建议以后可以命名更规范。

KaiwuDB也提供了认证培训课程，感兴趣的朋友可以登录如下网址学习：https://www.kaiwudb.com/learning/。