【KWDB 创作者计划】_二进制安装部署 KWDB 踩过的坑和经验
使用 KaiwuDB 二进制安装包在单个节点上以非安全模式部署并启动 KaiwuDB,操作系统为Kylin-Server-V10-SP3-2403-Release-20240426-x86_64。
KWDB介绍
KWDB 是由开放原子开源基金会孵化及运营的开源项目,是一款面向 AIoT 场景的分布式多模数据库产品,支持在同一实例同时建立时序库和关系库。
KWDB 基于浪潮 KaiwuDB 分布式多模数据库研发开源,典型应用场景包括但不限于物联网、能源电力、交通车联网、智慧政务、IT 运维、金融证券等,旨在为各行业领域提供一站式数据存储、管理与分析的基座,助力企业数智化建设,以更低的成本挖掘更大的数据价值。
KWDB 为不同角色开发者提供以下支持(包括但不限于):
- 为开发者提供通用连接接口,具备高速写入、极速查询、SQL 支持、随需压缩、数据生命周期管理、集群部署等特性,与第三方工具无缝集成,降低开发及学习难度,提升开发使用效率。
- 为运维管理人员提供快速安装部署、升级、迁移、监控等能力,降低数据库运维管理成本。
软硬件环境要求
操作系统及架构
KaiwuDB 支持在以下服务器操作系统进行安装部署。
这个地方一定要注意,我用的CentOS7.9编译安装过程中就遇到难解的报错,和厂家技术人员沟通得知该操作系统不支持裸机,安装前一定要注意看该部分操作系统和硬件的要求。
操作系统 | 版本 | 架构 | 容器 | 裸机 |
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 | √ | √ |
说明
未提及的操作系统版本也许可以运行 KaiwuDB,但尚未得到 KaiwuDB 官方支持。
推荐的版本是KylinOS SP3,因为SP2和SP1会有一些依赖或者链接库版本不太对 ,会比较麻烦。
硬件环境
项目 | 要求 |
CPU 和内存 | 单节点配置建议不低于 4 核 8G。对于数据量大、复杂的工作负载、高并发和高性能场景,建议配置更高的 CPU 和内存资源以确保系统的高效运行。 |
磁盘 | - 推荐使用 SSD 或者 NVMe 设备,尽量避免使用 NFS、CIFS、CEPH 等共享存储。 。 |
文件系统 | 建议使用 ext4 文件系统。 |
端口说明
下表列出 KaiwuDB 服务需要映射的端口。在安装部署前,确保目标机器的以下端口没有被占用且没有被防火墙拦截。在安装部署时,用户可以修改 deploy.cfg
文件中的端口配置参数。
端口号 | 说明 |
| 数据库 Web 服务端口 |
| 数据库服务端口和对外连接端口 |
依赖包说明
KWDB 支持在 Linux 操作系统进行安装部署,下表列出了编译和运行 KWDB 所需的软件依赖。
编译依赖:
依赖 | 版本 | 说明 |
ca-certificates | any | |
Go | v1.15+ | 查版本:go version |
CMake | v3.23 | cmake --version |
Autoconf | v2.68+ | |
goyacc | v0.8.0+ | |
dpkg-dev | any | 仅适用Ubuntu系统。 |
devscripts | any | 仅适用Ubuntu系统。 |
build-essential | any | |
checkinstall | any | |
libssl | v1.1.1+ | - Ubuntu系统该依赖名为libssl-dev。 |
libprotobuf | v3.6.1+ | - Ubuntu系统该依赖名为libprotobuf-dev。 |
liblzma | v5.2.0+ | - Ubuntu系统该依赖名为liblzma-dev。 |
libncurses | v6.2.0+ | - Ubuntu系统该依赖名为libncurses5-dev。 |
libatomic | v7.3.0+ | 仅 GCC 和 G++ 7.3.0 版本需要增加此依赖。 |
libstdc++-static | v7.3.0+ | 仅 GCC 和 G++ 7.3.0 版本需要增加此依赖。 |
protobuf-compiler | any | |
git | any |
运行依赖:
依赖 | 版本 |
openssl | v1.1.1+ |
libprotobuf | v3.6.1+ 指定高版本路径。 |
geos | v3.3.8+ |
xz-libs | v5.2.0+ |
squashfs-tools | any |
libgcc | v7.3.0+ |
mount | any |
squashfuse | any |
安装前准备
配置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 技术支持人员获取。
- 源码:源码编译目前支持单节点非安全模式部署。
下载安装包并解压
本文档采用下载二进制最新版 KWDB 2.2.0介质进行安装。
官网:https://www.kaiwudb.com
Gitee 社区:https://gitee.com/kwdb/kwdb
下载链接:https://foruda.gitee.com/attach_file/1743423049598005740/kwdb-2.2.0-kylinv10_2403-x86_64-rpms.tar.gz?token=41b11521084d6ad9d89e6d409b019afb&ts=1743658403&attname=KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz
特别注意:
建议使用二进制部署,因为源码会因为依赖导致安装失败耗时长
下载安装介质时一定要看清楚看准确,避免出现大版本匹配小版本不匹配导致的推倒重来。
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 数据库创建用户。 |
| 安装部署配置文件,用于配置部署节点的 IP 地址、端口等配置信息。 |
| 安装部署脚本,用于安装、卸载、启动、状态获取、关停和重启等操作。 |
| 存放 DEB、RPM、镜像包和 libprotobuf 包。 |
| 存放工具类脚本。 |
安装过程
部署 KaiwuDB 时,系统将对配置文件、运行环境、硬件配置和软件依赖进行检查。如果相应硬件未能满足要求,系统将继续安装,并提示硬件规格不满足要求。如果软件依赖未能满足要求,系统将中止安装,并提供相应的提示信息。
在部署过程中,系统会自动生成相关日志。如果部署时出现错误,用户可以通过查看终端输出或 KaiwuDB 安装目录中 log
目录里的日志文件,获取详细的错误信息。
部署完成后,系统会将 KaiwuDB 封装成系统服务(名称为 kaiwudb
),并生成以下文件:
kaiwudb.service
:配置 KaiwuDB 的 CPU 资源占用率。kaiwudb_env
:配置 KaiwuDB 启动参数。
编辑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 服务端口。
为 deploy.sh
脚本添加运行权限
chmod +x ./deploy.sh
执行单机部署安装命令
会自动创建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'.
重新加载 systemd
守护进程的配置文件
systemctl daemon-reload
启动 KaiwuDB 节点
以下启动是手动启动,服务器异常断电或重启后需手动再次手动启动,建议配置开启自启
./deploy.sh start
启动成功会输出如下:
[root@localhost kwdb_install]# ./deploy.sh start
[START COMPLETED]:KaiwuDB start successfully.
查看 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
特别注意:下载安装介质时一定要看清楚看准确,避免出现大版本匹配小版本不匹配导致的推倒重来。
配置 KWDB 开机自启动
配置 KWDB 开机自启动后,如果系统重启,则自动启动 KWDB。
systemctl enable kaiwudb
访问KWDB
管理用户访问
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>
普通用户访问
root用户连接 KaiwuDB,创建普通用户后,root用户退出登录,使用新创建的普通用户连接 KaiwuDB。
创建普通用户
--root用户连接 KaiwuDB
kwbase sql --insecure --host=192.168.40.115
--创建普通用户
CREATE USER top;
--root用户退出登录
\q
普通用户连接 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
配置连接
连接后界面显示如下:
卸载过程
停止 KWDB 服务
systemctl stop kaiwudb
卸载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 delete or keep all user data. Please confirm your choice: Do you want to delete the data? (y/N)y
[UNINSTALL COMPLETED]:KaiwuDB has been uninstalled successfully.
参考链接:征文大赛 |「码」上数据库—— KWDB 2025 创作者计划启动
→ 安装部署文档:
https://www.kaiwudb.com/kaiwudb_docs/#/oss_v2.2.0/quickstart/overview.html
特别提示:为了保证顺利安装,请注意不同系统的版本配置与依赖哦。
→ 安装部署视频合集:
KaiwuDB的个人空间-KaiwuDB个人主页-哔哩哔哩视频
→ 技术贴合集:
https://mp.weixin.qq.com/mp/appmsgalbum?__biz=Mzk0OTQyNjUxNA==&action=getalbum&album_id=3734076525876903936#wechat_redirect
放假期间,如有遇到问题