一、部署概要
KaiwuDB 是浪潮出品的一款面向 AIoT 场景的分布式、多模融合、支持原生 AI 的数据库产品，支持同一实例同时建立时序库和关系库并融合处理多模数据，具备时序数据高效处理能力，具有稳定安全、高可用、易运维等特点。面向工业物联网、数字能源、车联网、智慧产业等领域，KWDB 提供一站式数据存储、管理与分析的基座。长期位居时序数据库排名前二。
KWDB 是 KaiwuDB 的社区版，目前已更新到KWDB 2.2.0 版本。KWDB 2.2.0 版本在保持原有特性的基础上，针对时间精度、数据库对象、DML 操作、数据查询及数据库运维等方面进行了优化与增强。
KWDB 支持使用裸机或容器安装包部署单节点或集群。本文演示麒麟 KYLIN V10 SP3环境下单节点裸机部署KWDB 2.2.0。
二、部署前准备
1、软硬件环境要求
KWDB 支持在以下服务器操作系统进行安装部署。
|
操作系统 |
版本 |
架构 |
容器 |
裸机 |
|
Anolis |
7 |
ARM_64 |
√ |
- |
|
7 |
x86_64 |
√ |
- |
|
|
8 |
ARM_64 |
√ |
√ |
|
|
8 |
x86_64 |
√ |
√ |
|
|
CentOS |
7 |
x86_64 |
√ |
- |
|
8 |
x86_64 |
√ |
- |
|
|
Debian |
V11 |
ARM_64 |
√ |
- |
|
KylinOS |
V10 |
ARM_64 |
√ |
√ |
|
V10 |
x86_64 |
√ |
√ |
|
|
openEuler |
22.03 |
x86_64 |
√ |
- |
|
Ubuntu |
V18.04 |
x86_64 |
√ |
√ |
|
V20.04 |
ARM_64 |
√ |
√ |
|
|
V20.04 |
x86_64 |
√ |
√ |
|
|
V22.04 |
ARM_64 |
√ |
√ |
|
|
V22.04 |
x86_64 |
√ |
√ |
|
|
V24.04 |
ARM_64 |
√ |
√ |
|
|
V24.04 |
x86_64 |
√ |
√ |
|
|
UOS |
V20 |
x86_64 |
√ |
√ |
|
V20 |
ARM_64 |
√ |
√ |
硬件要求：
|
项目 |
要求 |
|
CPU
和内存 |
单节点配置建议不低于 4 核 8G。对于数据量大、复杂的工作负载、高并发和高性能场景，建议配置更高的 CPU 和内存资源以确保系统的高效运行。 |
|
磁盘 |
推荐使用 SSD 或者 NVMe 设备，尽量避免使用 NFS、CIFS、CEPH 等共享存储。 |
|
文件系统 |
建议使用 ext4 文件系统。 |
2、软件依赖
安装时，KWDB 会对依赖进行检查。如果缺少依赖会退出安装并提示依赖缺失。
下表列出需要在目标机器安装的依赖：
|
依赖 |
版本 |
说明 |
|
OpenSSL |
v1.1.1+ |
N/A |
|
libprotobuf |
v3.6.1+ |
Ubuntu
18.04 版本默认的 libprotobuf 版本低于所需版本，用户需要在部署前提前安装高版本的
libprotobuf 或者使用安装包内提供的高版本 libprotobuf 完成安装。具体操作说明，参见libprotobuf
安装。 |
|
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 |
可选依赖 |
3、端口要求
下表列出 KWDB 服务需要映射的端口。在安装部署前，确保目标机器的以下端口没有被占用且没有被防火墙拦截。在安装部署时，用户可以修改 deploy.cfg 文件中的端口配置参数。
|
端口号 |
说明 |
|
8080 |
数据库 Web 服务端口 |
|
26257 |
数据库服务端口和对外连接端口 |
三、部署 KWDB
部署 KWDB 时，系统将对配置文件、运行环境、硬件配置和软件依赖进行检查。如果相应硬件未能满足要求，系统将继续安装，并提示硬件规格不满足要求。如果软件依赖未能满足要求，系统将中止安装，并提供相应的提示信息。
在部署过程中，系统会自动生成相关日志。如果部署时出现错误，用户可以通过查看终端输出或 KWDB 安装目录中 log 目录里的日志文件，获取详细的错误信息。
部署完成后，系统会将 KWDB 封装成系统服务（名称为 KaiwuDB），并生成以下文件：
- KaiwuDB.service：配置 KWDB 的 CPU 资源占用率。
- kaiwudb_env：配置 KWDB 启动参数。
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
解压后生成的目录包含以下文件：
|
文件 |
说明 |
|
add_user.sh |
安装、启动 KWDB 后，为 KaiwuDB 数据库创建用户。 |
|
deploy.cfg |
安装部署配置文件，用于配置部署节点的 IP 地址、端口等配置信息。 |
|
deploy.sh |
安装部署脚本，用于安装、卸载、启动、状态获取、关停和重启等操作。 |
|
packages 目录 |
存放 DEB、RPM、镜像包和
libprotobuf 包。 |
|
utils 目录 |
存放工具类脚本。 |
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
2.为 deploy.sh 脚本添加运行权限。
chmod +x ./deploy.sh
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、启动 KWDB 节点。
./deploy.sh start
执行成功后，控制台输出以下信息：
START COMPLETED: KaiwuDB has started successfuly.
4、查看 KWDB 节点状态。
./deploy.sh status
[STATUS COMPLETED]: KaiwuDB is runnning now.
systemctl status kaiwudb
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.
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 操作：
1、使用 kwbase CLI 工具连接 KWDB
kwbase 是 KWDB 提供的内置命令行工具。用户可以通过 kwbase 以安全模式（适用于生产环境）或非安全模式（适用于测试）连接 KWDB，进行数据库操作和维护。
# 用户连接 KWDB。不指定-u，默认root登录。
#非安全模式
kwbase sql --insecure --host=
#默认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;
2、安装 KaiwuDB 开发者中心连接 KWDB
获取系统环境对应的 DEB 或 RPM 安装包，然后解压缩安装包，调用图形化界面连接数据库。
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’
Win系统：
解压KaiwuDB_Developer_Center-2.0.4-win-x86_64.zip。
双击 KaiwuDB Developer Center.exe，创建新连接。
3、常用查询
数据库版本查看
SELECT 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;
使用 SELECT 语句通过一个或多个返回字段查看特定会话。
SELECT * FROM [SHOW ALL CLUSTER SESSIONS] WHERE user_name = ‘root’;
取消会话
CANCEL SESSION 语句用于停止长时间运行的会话。
取消单个会话。
– 取消特定ID的会话：
CANCEL SESSION ‘session_id’;
取消多个会话。
CANCEL SESSIONS (SELECT session_id FROM [SHOW SESSIONS] WHERE user_name = ‘kaiwudb’);
五、KWDB 服务启动与停止
1、使用脚本启停
./deploy.sh stop
KaiwuDB stop successfully.
./deploy.sh start
[START COMPLETED]: KaiwuDB start successfully.
./deploy.sh status
[STATUS COMPLETED]: KaiwuDB is runnning now.
2、使用系统服务名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
七、问题整理
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核配置引起，重新调整启动正常。
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>
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/。
