原文链接：【KWDB 创作者计划】KWDB新手上路：轻松掌握KWDB数据库的单机部署-CSDN博客

作者：江湖有缘

前言

KWDB是一款高性能、强一致、分布式多模型数据库，适用于物联网、金融、工业控制等多种高实时性场景。随着数字化转型的加速，越来越多开发者和技术爱好者开始关注并尝试部署使用 KWDB。本文面向初次接触 KWDB 的用户，详细介绍如何在单机环境下完成 KWDB 数据库的快速部署与基础操作，帮助大家快速上手，迈出使用 KWDB 的第一步。

一、KWDB介绍

1.1 KWDB简介

KWDB 是一款面向 AIoT 场景的分布式、多模融合数据库产品。 支持在同一个实例中建立时序库和关系库，并统一处理多种类型的数据，具备对海量时序数据的高效读写与分析能力。 产品具备高可用、安全稳定、易运维等特性，广泛应用于工业物联网、数字能源、车联网、智慧矿山等多个行业领域，为用户提供一站式数据存储、管理与分析的基础平台。

1.2 主要特点

• 高性能处理能力：支持海量时序数据高速读写，提供插值查询、数学函数等丰富的时序特色功能，提升应用效率。

• 低运管成本：统一存储与管理多模数据，一套系统满足跨业务、跨部门数据融合需求，降低企业IT与运维投入。

• 低存储成本：支持 5-30 倍数据压缩比，结合数据生命周期管理策略，灵活控制数据保留时间，显著节省存储资源。

• 高安全性：提供数据库审计与加密机制，保障数据在复杂业务场景下的安全稳定运行。

• 易用性强：提供标准 SQL 接口、高速写入、极速查询、集群部署等能力，与第三方工具无缝集成，开发运维更便捷。

1.3 典型应用场景

二、本次实践介绍

2.1 部署环境要求

• KWDB数据库的硬件规格要求

  

• KWDB 支持在以下已安装 Docker的操作系统中进行容器部署

2.2 本地环境规划

本次实践为个人测试环境，操作系统版本为Ubuntu 22.04.1。

2.3 本次实践说明

1. 本次实践基于个人测试环境操作，生产环境中请谨慎应用相关配置和操作。

2. 本次实践旨在为新手提供 KaiwuDB（KWDB）数据库的体验与实践指导。

3. 实践内容包括使用 KaiwuDB 的二进制安装包进行单节点部署与安装。

4. 实践目标是帮助用户掌握 KWDB数据库的基础操作与基本管理技能。

三、下载软件包

3.1 创建下载目录

创建下载目录/data/kwdb

mkdir -p /data/kwdb && cd /data/kwdb

3.2 下载KWDB安装包

执行以下命令，下载KWDB安装包。

wget https://gitee.com/kwdb/kwdb/releases/download/V2.2.0/KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz

3.3 解压软件包

• 执行以下命令，解压KWDB软件包。

tar -xzf KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz

• 查看软件包解压后，内容如下所示：

root@jeven01:/data/kwdb# ll kwdb_install/
total 52
drwxr-xr-x 4 root root  4096 May  5 09:19 ./
drwxr-xr-x 3 root root  4096 May  5 09:17 ../
-rwxr-xr-x 1 root root  2024 Mar 31 07:11 add_user.sh*
-rw-r--r-- 1 root root  3605 Mar 31 07:12 .construction_var
-rw-r--r-- 1 root root   246 May  5 09:01 deploy.cfg
-rwxr-xr-x 1 root root 24410 Mar 31 07:11 deploy.sh*
drwxr-xr-x 2 root root  4096 Mar 31 07:22 packages/
drwxr-xr-x 2 root root  4096 Mar 31 07:11 utils/

四、部署KWDB数据库

4.1 编辑配置文件

在解压目录 kwdb_install/ 中，编辑 deploy.cfg 配置文件以设置安全模式、管理用户和服务端口等信息。

vim kwdb_install/deploy.cfg

[global]
# Whether to turn on secure mode
secure_mode=tls
# Management KaiwuDB user
management_user=kaiwudb
# KaiwuDB cluster http port
rest_port=8080
# KaiwuDB service port
kaiwudb_port=26257
# KaiwuDB data directory
data_root=/data/kwdb/kaiwudb
# CPU usage[0-1]
# cpu=1
[local]
# local node configuration
node_addr=192.168.3.88
# 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
~

deploy.cfg 配置文件说明

• 全局配置（[global]）

• 点配置（[local]）

4.2 进入软件目录

进入KWDB软件目录，如下所示：

root@jeven01:/data/kwdb# cd kwdb_install/
root@jeven01:/data/kwdb/kwdb_install# ls
add_user.sh  deploy.cfg  deploy.sh  packages  utils

4.3 添加运行权限。

执行以下命令，为 deploy.sh 脚本添加运行权限。

chmod +x ./deploy.sh

4.4 第一次安装报错

我们执行以下命令，启动单节点部署流程，使用部署脚本 deploy.sh 一键完成KWDB的安装与配置。

./deploy.sh install --single

在遵循官方文档进行安装的过程中，遇到了错误提示 libprotobuf23 未安装的问题。当前系统为 Ubuntu 22.04.1 LTS，在按照指南从提供的 KWDB 安装包中寻找适用于本系统的依赖项时，发现 packages 目录下缺少 libprotobuf23_3.12.4_amd64.deb 文件。鉴于此情况，我们需要手动重新安装 libprotobuf23 库以解决该问题并继续完成 KWDB 的部署。

4.5 重新安装KWDB数据库

执行以下命令，我们手动安装 libprotobuf23 库。

apt install libprotobuf23 -y

我们重新使用部署脚本 deploy.sh 一键完成KWDB的安装与配置。

./deploy.sh install --single

在安装过程中，系统会提示您输入新增用户 jeven 的密码，请按指示自行输入。请注意，本次实践基于配置为4核CPU和8GB内存的虚拟机环境。由于该配置可能触发“CPU规格不满足要求”的警告，建议根据实际需求调整虚拟机规格以避免此类警告。提升机器的硬件配置（如增加CPU核心数）可以有效解决这一问题。

安装成功后，会出现以下提示信息。

4.6 启动KWDB节点

执行以下命令，重新加载 systemd 守护进程的配置文件。

systemctl daemon-reload

启动KWDB数据库，如下所示：

./deploy.sh start

执行以下命令，设置KWDB服务开自启。

systemctl enable kaiwudb

4.7 查看KWDB数据库状态

我们执行以下命令，查看KWDB数据库状态。

root@jeven01:/data/kwdb/kwdb_install# ./deploy.sh status
[STATUS COMPLETED]:KaiwuDB is not runnning.

也可以使用systemctl status kaiwudb命令，查看KWDB服务状态。

systemctl status kaiwudb

4.8 新建用户

如果在安装过程中由于等待时间过长而未设置用户密码，或者遇到密码遗忘、登录失败等情况，可以通过执行 add_user.sh 脚本来创建新的数据库用户。此脚本提供了一种简便的方法来重新设定访问凭据，确保我们能够顺利恢复对数据库的管理与操作。

./add_user.sh

五、访问KWDB数据库

5.1 kwbase CLI工具访问KWDB

我们使用以下命令，用新建的test用户 kwbase CLI工具访问KWDB。

kwbase sql --certs-dir=/etc/kaiwudb/certs   --host=192.168.3.88 -u test

5.2 查询数据库版本

执行以下命令，我们可以查询KWDB数据库版本，可以看到当前安装的数据库版本为KaiwuDB 2.2.0。

test@192.168.3.88:26257/defaultdb> ｓｅｌｅｃｔ version();
                                       version
--------------------------------------------------------------------------------------
  KaiwuDB 2.2.0 (x86_64-linux-gnu, built 2025/03/31 07:20:02, go1.16.15, gcc 11.4.0)
(1 row)
Time: 360.181µs
test@192.168.3.88:26257/defaultdb>

六、注意事项

在部署 KWDB 数据库的过程中，可能会遇到一些常见问题。以下是我在实际操作中总结的一些注意事项及解决方案，供新手用户参考，帮助大家更顺利地完成部署。

6.1 缺少依赖包 libprotobuf23_3.12.4_amd64.deb

在部署过程中，若发现 packages 目录下缺少 libprotobuf23_3.12.4_amd64.deb 文件，会导致安装中断或失败。

解决方法：

请手动下载并重新安装该依赖库文件：

apt ｕｐｄａｔｅ
apt install libprotobuf23

确保依赖项安装完整后，再继续部署 KWDB。

6.2 磁盘空间不足导致部署失败或系统卡顿

在多次卸载、重装数据库的过程中，如果服务器磁盘空间预留不足，容易引发系统卡顿甚至崩溃。

建议做法：

• 部署前确保服务器至少预留 20GB 以上的可用空间。

• 定期清理不必要的安装包和日志文件，避免重复安装造成的空间浪费。

• 使用 df -h 命令实时监控磁盘使用情况。

6.3.数据库连接失败，建议通过脚本新建用户

部署完成后，若使用默认账户连接数据库失败，可能是由于权限配置不正确或用户未被正确创建。

推荐解决方案：

使用安装包中的 add_user.sh 脚本创建新用户，以确保能够成功连接数据库：

./add_user.sh

创建完成后，使用新用户登录数据库即可正常操作。

6.4 服务器配置要求

KWDB 对系统资源有一定要求，若服务器配置过低，可能导致部署失败或运行不稳定。

最低配置建议：

建议在满足以上条件的环境中部署，以保证安装过程顺利以及数据库稳定运行。

七、总结

通过本次实践，我们完整地完成了 KWDB 数据库的下载、部署、配置、启动及基础访问操作，掌握了单机环境下部署 KWDB 的关键步骤和常见问题处理方法。整个过程虽然遇到了依赖缺失、磁盘空间不足等典型问题，但通过逐一排查和合理调整，最终成功搭建起运行环境。此次实践不仅提升了对 KWDB 架构和部署流程的理解，也为后续深入学习和应用打下了坚实基础。希望本指南能为更多技术爱好者提供实用参考，助力高效入门 KWDB 数据库。