本文转载自【KWDB 2025 创作者计划】征文大赛优秀作品

原文链接：【KWDB 2025 创作者计划】_二进制安装部署 KWDB 踩过的坑和经验 - 墨天轮

原作者：董小姐

使用 KaiwuDB 二进制安装包在单个节点上以非安全模式部署并启动 KaiwuDB，操作系统为 Kylin-Server-V10-SP3-2403-Release-20240426-x86_64。

一、KWDB介绍

KWDB 是由开放原子开源基金会孵化及运营的开源项目，是一款面向 AIoT 场景的分布式多模数据库产品，支持在同一实例同时建立时序库和关系库。

KWDB 基于浪潮 KaiwuDB 分布式多模数据库研发开源，典型应用场景包括但不限于物联网、能源电力、交通车联网、智慧政务、IT 运维、金融证券等，旨在为各行业领域提供一站式数据存储、管理与分析的基座，助力企业数智化建设，以更低的成本挖掘更大的数据价值。

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

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

二、软硬件环境要求

2.1 操作系统及架构

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

这个地方一定要注意，我用的CentOS7.9编译安装过程中就遇到难解的报错，和厂家技术人员沟通得知该操作系统不支持裸机，安装前一定要注意看该部分操作系统和硬件的要求。

说明：

1. 未提及的操作系统版本也许可以运行 KaiwuDB，但尚未得到 KaiwuDB 官方支持。
2. 推荐的版本是KylinOS SP3，因为SP2和SP1会有一些依赖或者链接库版本不太对 ，会比较麻烦。

2.2 硬件环境

2.3 端口说明

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

三、依赖包说明

KWDB 支持在 Linux 操作系统进行安装部署，下表列出了编译和运行 KWDB 所需的软件依赖。

编译依赖：

运行依赖：

四、安装前准备

4.1 配置yum

上传Kylin-Server-V10-SP3-2403-Release-20240426-x86_64.iso至服务器/soft目录并挂载

#配置本地yum源
cd /etc/yum.repos.d
mkdir bk
mv *.repo bk/


cat > /etc/yum.repos.d/kylinv10sp3.repo << "EOF"
[local]
name=kylinv10sp3
baseurl=file:///mnt
gpgcheck=0
enabled=1
EOF

mount /opt/Kylin-Server-V10-SP3-General-Release-2303-X86_64.iso  /mnt


#安装所需的软件
yum install -y gcc-c++
yum install -y  libprotobuf-dev 
yum install -y  protobuf-compiler

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

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

4.2 下载安装包并解压

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

官网： https://www.kaiwudb.com/

Gitee 社区：https://gitee.com/kwdb/kwdb

特别注意：

建议使用二进制部署，因为源码会因为依赖导致安装失败耗时长

下载安装介质时一定要看清楚看准确，避免出现大版本匹配小版本不匹配导致的推倒重来。

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

二进制下载地址：https://gitee.com/kwdb/kwdb/releases/tag/V2.2.0

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

五、安装过程

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

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

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

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

5.1 编辑deploy.cfg 配置文件

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

说明

默认情况下，deploy.cfg 配置文件中包含集群配置参数。请删除或注释 [cluster] 集群配置项。

cd kwdb_install/

cp deploy.cfg deploy.cfg_bak

vi deploy.cfg
[global]
# Whether to turn on secure mode
secure_mode=insecure
# 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.40.115
# section cluster is optional
[cluster]
# remote node addr,split by ','
#node_addr=127.0.0.2,127.0.0.3
# ssh info
#ssh_port=22
#ssh_user=admin

参数说明：

• global：全局配置
• secure_mode：是否开启安全模式，支持以下三种取值：
• insecure：使用非安全模式。
• tls：（默认选项）开启 TLS 安全模式。开启安全模式后，KaiwuDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
• tlcp：开启 TLCP 安全模式。开启安全模式后，KaiwuDB 生成 TLCP 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /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]，最大精度为小数点后两位。注意：如果部署环境为 Ubuntu 18.04 版本，部署完成后，需要将 kaiwudb.service 文件中的 CPUQuota 修改为整型值，例如，将 180.0% 修改为 180%，以确保设置生效。具体操作步骤，参见配置 CPU 资源占用率。
• encrypto_store: 可选参数，用于在部署时启用关系数据库存储加密功能。默认情况下，该参数不会显示，需要用户手动添加到配置文件中并设置为 true。启用后，系统将在 /etc/kaiwudb/certs 目录下自动生成存储密钥，使用 SM4 加密算法对数据进行加密。KaiwuDB 支持通过 --store-encryption 启动参数，在部署后进行目录加密、解密、存储密钥更新和算法更换等操作，更多信息，参见存储加密。
• local：本地节点配置
• node_addr：本地节点对外提供服务的 IP 地址，监听地址为 0.0.0.0，端口为 KaiwuDB 服务端口。

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

chmod +x ./deploy.sh

5.3 执行单机部署安装命令

会自动创建kaiwudb用户

./deploy.sh install --single

返回如下说明部署成功：

[root@localhost kwdb_install]# ./deploy.sh install --single
 [WARN] 2025-04-03 17:25:59 The number of CPU cores does not meet the requirement. KaiwuDB may running failed. 
[INSTALL COMPLETED]:KaiwuDB has been installed successfully! To start KaiwuDB, please execute the command 'systemctl daemon-reload'.

问题处理

[cluster]node_addr is missing in deploy.cfg

--问题描述
[root@localhost kwdb_install]# ./deploy.sh install --single
 [WARN] 2025-04-03 14:10:11 The number of CPU cores does not meet the requirement. KaiwuDB may running failed. 
 [ERROR] 2025-04-03 14:10:11 [cluster]node_addr is missing in deploy.cfg. 

--解决办法
vi deploy.cfg
#[cluster]
# remote node addr,split by ','
#node_addr=127.0.0.2,127.0.0.3
# ssh info
#ssh_port=22
#ssh_user=admin

需全部注释掉

CA certificate creats failed

--问题描述
./deploy.sh install --single
 [WARN] 2025-04-03 14:12:41 The number of CPU cores does not meet the requirement. KaiwuDB may running failed. 
 [ERROR] 2025-04-03 14:12:45 CA certificate creats failed: ./kwbase: error while loading shared libraries: libprotobuf.so.25: cannot open shared object file: No such file or directory

--解决过程
 更改配置文件，使用非安全模式 secure_mode=tls 改成 secure_mode=insecure

Create user failed: 无效的密码

--问题描述
[root@localhost kwdb_install]# ./deploy.sh install --single
 [WARN] 2025-04-03 17:24:12 The number of CPU cores does not meet the requirement. KaiwuDB may running failed. 
 [ERROR] 2025-04-03 17:24:27 Create user failed: 无效的密码： 密码少于 8 个字符 chpasswd: (user kaiwudb) pam_chauthtok() failed, error: 鉴定令牌操作错误 chpasswd：(第 1 行，用户 kaiwudb) 密码未更改

--问题原因
密码复杂度不够

--解决办法
换用复杂密码安装成功
[root@localhost kwdb_install]# ./deploy.sh install --single
 [WARN] 2025-04-03 17:25:59 The number of CPU cores does not meet the requirement. KaiwuDB may running failed. 
[INSTALL COMPLETED]:KaiwuDB has been installed successfully! To start KaiwuDB, please execute the command 'systemctl daemon-reload'.

5.4重新加载 systemd 守护进程的配置文件

systemctl daemon-reload

5.5 启动 KaiwuDB 节点

以下启动是手动启动，服务器异常断电或重启后需手动再次手动启动，建议配置开启自启

./deploy.sh start

启动成功会输出如下：

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

5.6 查看 KWDB 节点状态

./deploy.sh status

或

systemctl status kaiwudb

分别输出如下：

[root@localhost kwdb_install]# ./deploy.sh status
[STATUS COMPLETED]:KaiwuDB is runnning now.
[root@localhost 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-04-08 15:46:38 CST; 20s ago
  Process: 35895 ExecStartPre=/usr/bin/sudo /usr/sbin/sysctl -w vm.max_map_count=10000000 (code=exited, status=0/SUCCESS)
 Main PID: 35905 (kwbase)
    Tasks: 34
   Memory: 386.2M
   CGroup: /system.slice/kaiwudb.service
           └─35905 /usr/local/kaiwudb/bin/kwbase start-single-node --insecure --listen-addr=0.0.0.0:26257 --advertise-addr=12.168.40.115:26257 --http-addr=0.0.0.0:8080 --store=/var/lib/kaiwudb

4月 08 15:46:39 localhost.localdomain kwbase[35905]: sql:                 postgresql://root@12.168.40.115:26257?sslmode=disable
4月 08 15:46:39 localhost.localdomain kwbase[35905]: RPC client flags:    /usr/local/kaiwudb/bin/kwbase <client cmd> --host=12.168.40.115:26257 --insecure
4月 08 15:46:39 localhost.localdomain kwbase[35905]: logs:                /var/lib/kaiwudb/logs
4月 08 15:46:39 localhost.localdomain kwbase[35905]: temp dir:            /var/lib/kaiwudb/kwbase-temp050856400
4月 08 15:46:39 localhost.localdomain kwbase[35905]: external I/O path:   /var/lib/kaiwudb/extern
4月 08 15:46:39 localhost.localdomain kwbase[35905]: store[0]:            path=/var/lib/kaiwudb
4月 08 15:46:39 localhost.localdomain kwbase[35905]: storage engine:      rocksdb
4月 08 15:46:39 localhost.localdomain kwbase[35905]: status:              initialized new cluster
4月 08 15:46:39 localhost.localdomain kwbase[35905]: clusterID:           69696561-bbd3-47e1-9b91-cb2919a2565a
4月 08 15:46:39 localhost.localdomain kwbase[35905]: nodeID:              1

问题处理

kwdb is not running

问题描述

启动KWDB正常，但是查看状态显示未运行，安装过程如下：

[root@localhost kwdb_install]# cat deploy.cfg
[global]
# Whether to turn on secure mode
secure_mode=insecure
# 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.40.115
# section cluster is optional
#[cluster]
# remote node addr,split by ','
#node_addr=127.0.0.2,127.0.0.3
# ssh info
#ssh_port=22
#ssh_user=admin
[root@localhost kwdb_install]# chmod +x ./deploy.sh
[root@localhost kwdb_install]# ./deploy.sh install --single
 [WARN] 2025-04-08 18:18:59 The number of CPU cores does not meet the requirement. KaiwuDB may running failed. 
[INSTALL COMPLETED]:KaiwuDB has been installed successfully! To start KaiwuDB, please execute the command 'systemctl daemon-reload'.
[root@localhost kwdb_install]# systemctl daemon-reload
[root@localhost kwdb_install]# ./deploy.sh start
[START COMPLETED]:KaiwuDB start successfully.
[root@localhost kwdb_install]# ./deploy.sh status
[STATUS COMPLETED]:KaiwuDB is not runnning.
[root@localhost kwdb_install]# systemctl status kaiwudb
● kaiwudb.service - KaiwuDB Service
   Loaded: loaded (/etc/systemd/system/kaiwudb.service; disabled; vendor preset: disabled)
   Active: failed (Result: exit-code) since Tue 2025-04-08 18:19:43 CST; 15s ago
  Process: 4569 ExecStartPre=/usr/bin/sudo /usr/sbin/sysctl -w vm.max_map_count=10000000 (code=exited, status=0/SUCCESS)
  Process: 4579 ExecStart=/usr/local/kaiwudb/bin/kwbase start-single-node $KAIWUDB_START_ARG --insecure --listen-addr=0.0.0.0:26257 --advertise-addr=192.168.40.115:26257 ->
 Main PID: 4579 (code=exited, status=127)

4月 08 18:19:43 localhost.localdomain systemd[1]: Starting KaiwuDB Service...
4月 08 18:19:43 localhost.localdomain sudo[4569]:  kaiwudb : TTY=unknown ; PWD=/usr/local/kaiwudb/bin ; USER=root ; COMMAND=/usr/sbin/sysctl -w vm.max_map_count=10000000
4月 08 18:19:43 localhost.localdomain systemd[1]: Started KaiwuDB Service.
4月 08 18:19:43 localhost.localdomain kwbase[4579]: /usr/local/kaiwudb/bin/kwbase: symbol lookup error: /usr/local/kaiwudb/bin/kwbase: undefined symbol: _ZN6google8protobu>
4月 08 18:19:43 localhost.localdomain systemd[1]: kaiwudb.service: Main process exited, code=exited, status=127/n/a
4月 08 18:19:43 localhost.localdomain systemd[1]: kaiwudb.service: Failed with result 'exit-code'.

问题原因

kylin v10 sp3 2303的操作系统上安装KWDB-Kylin v10 sp3 2403的包，依赖不匹配。错误信息在systemctl status里。

解决办法

重装Kylin v10 sp3 2403 操作系统后再安装KWDB-Kylin v10 sp3 2403

特别注意：下载安装介质时一定要看清楚看准确，避免出现大版本匹配小版本不匹配导致的推倒重来。

5.7 配置 KWDB 开机自启动

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

systemctl enable kaiwudb

六、访问KWDB

6.1 管理用户访问

root 用户连接 KaiwuDB

--语法
kwbase sql --insecure --host=<your-host-ip>

--示例
kwbase sql --insecure --host=192.168.40.115

输出如下：

[root@localhost kwdb_install]# kwbase sql --insecure --host=192.168.40.115
#
# Welcome to the KWDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
# Server version: KaiwuDB 2.2.0 (x86_64-linux-gnu, built 2025/03/31 07:20:16, go1.16.15, gcc 7.3.0) (same version as client)
# Cluster ID: 69696561-bbd3-47e1-9b91-cb2919a2565a
#
# Enter \? for a brief introduction.
#
root@192.168.40.115:26257/defaultdb> \l+
invalid syntax: \l+. Try \? for help.
root@192.168.40.115:26257/defaultdb> \l
  database_name | engine_type
----------------+--------------
  defaultdb     | RELATIONAL
  postgres      | RELATIONAL
  system        | RELATIONAL
(3 rows)

Time: 1.341848ms

root@192.168.40.115:26257/defaultdb>

6.2 普通用户访问

root用户连接 KaiwuDB，创建普通用户后，root用户退出登录，使用新创建的普通用户连接 KaiwuDB。

创建普通用户

--root用户连接 KaiwuDB
kwbase sql --insecure --host=192.168.40.115

--创建普通用户
create user top ;
ｇｒａｎｔ admin to top;

--root用户退出登录
\q

非安全模式下创建用户时不支持设置密码，设置密码会提示如下报错：

root@192.168.40.115:26257/defaultdb> create user top with password 'top'; ERROR: setting or updating a password is not supported in insecure mode SQLSTATE: 28P01

普通用户连接 KaiwuDB

--语法
kwbase sql --insecure --host=<your-host-ip> -u user1

--示例
kwbase sql --insecure --host=192.168.40.115 -u top

KaiwuDB数据库连接工具访问

数据开发者中心：支持通过可视化的页面满足开发者对数据库日常的运维、管理需求：包含登录、连接管理、SQL 工作台等功能离，并统一进行运维。

下载数据开发者中心

下载地址： https://gitee.com/kwdb/kwdb/releases/tag/V2.2.0

该工具是免安装，直接运行即可用。

配置连接

连接后界面显示如下：

七、卸载过程

7.1 停止 KWDB 服务

systemctl stop kaiwudb

7.2 卸载KWDB服务

确认是否删除数据目录。输入 y 将删除数据目录，取消 KWDB 数据目录下的 loop 设备挂载。输入 n 将保留数据目录。卸载完成后，控制台输出信息：KaiwuDB has been uninstalled successfully

cd /opt/kwdb/kwdb_install
./deploy.sh uninstall

输出如下：

[root@localhost kwdb_install]# ./deploy.sh uninstall
When uninstalling KaiwuDB, you can either ｄｅｌｅｔｅ or keep all user data. Please confirm your choice: Do you want to ｄｅｌｅｔｅ the data? (y/N)y
[UNINSTALL COMPLETED]:KaiwuDB has been uninstalled successfully.

KWDB 社区征文大赛活动链接： https://mp.weixin.qq.com/s/ZKQo7eQj_AtwamONCSl07A

→ 安装部署文档：

https://www.kaiwudb.com/kaiwudb_docs/#/oss_v2.2.0/quickstart/overview.html

特别提示：为了保证顺利安装，请注意不同系统的版本配置与依赖哦。

→ 安装部署视频合集：

https://space.bilibili.com/1533338997/lists/4441503?type=season

→ 技术贴合集：

https://mp.weixin.qq.com/mp/appmsgalbum?__biz=Mzk0OTQyNjUxNA==&action=getalbum&album_id=3734076525876903936#wechat_redirect