当前位置：首页 > news >正文

【KWDB 创作者计划】_本地化部署与使用KWDB 深度实践

news 来源：原创 2025/4/22 5:29:49

引言

KWDB 是一款面向 AIoT 场景的分布式多模数据库，由开放原子开源基金会孵化及运营。它能在同一实例同时建立时序库和关系库，融合处理多模数据，具备强大的数据处理能力，可实现千万级设备接入、百万级数据秒级写入、亿级数据秒级读取。

此外，它还具有稳定安全、高可用、易运维的特点，为开发者提供通用连接接口，方便与第三方工具集成，降低开发学习难度；为运维管理人员提供安装部署、升级等便捷操作，降低运维成本。其典型应用场景广泛，涉及物联网、能源电力、交通车联网等多个行业，致力于为企业数智化建设提供数据支持。

KWDB官网：浪潮 KaiwuDB 分布式多模数据库—多模一库，快人一步

本文将详细介绍 KWDB 在本地的部署和使用方法，帮助开发者快速上手。

引言

一、部署前的准备

（一）硬件要求

（二）操作系统支持

（三）软件依赖

（四）端口要求

二、获取安装包

三、开始部署

（一）配置 deploy.cfg 文件

（二）赋予 deploy.sh 脚本权限

（三）执行单机部署安装命令

（四）启动 KWDB 节点

（五）查看 KWDB 节点状态

（六）配置 KWDB 开机自启动

四、KWDB 的使用

（一）使用 KaiwuDB 开发者中心连接 KWDB

（二）使用 KaiwuDB JDBC 连接 KWDB（适合 Java 开发者）

一、部署前的准备

（一）硬件要求

CPU 和内存：建议不低于 4 核 8G。实际部署时，可根据业务规模和性能要求灵活规划硬件资源。例如，对于小型项目或测试环境，4 核 8G 的配置足以满足基本需求；但对于大型生产环境，若有大量数据处理任务，可能需要更高配置的 CPU 和更大容量的内存，如 8 核 16G 甚至更高。

磁盘：推荐使用 SSD 或者 NVMe 设备，这类存储设备读写速度快，能显著提升数据库性能。尽量避免使用 NFS、CIFS、CEPH 等共享存储，因为共享存储在数据传输和并发访问时可能会出现性能瓶颈。磁盘必须能够实现 500 IOPS 和 30 MB/s 处理效率。

文件系统：建议使用 ext4 文件系统，ext4 文件系统具有较好的稳定性和性能，对 KWDB 的支持较为友好。

（二）操作系统支持

KWDB 支持在多种服务器操作系统上进行安装部署，具体如下：

操作系统	版本	架构
CentOS	7.x 及以上	x86_64
Ubuntu	18.04 及以上	x86_64
Debian	10 及以上	x86_64

需注意，如使用上述未提及的操作系统，可能会存在兼容性问题，若遇到问题可及时与 KWDB 官方团队联系解决

（三）软件依赖

安装时，KWDB 会自动对依赖进行检查。若缺少依赖，安装将退出并提示缺失信息。若目标机器不能联网，需在能联网的机器上根据目标机器的操作系统下载好所有依赖文件，再复制到目标机器上进行安装

不同操作系统及安装包的依赖略有不同，以下是常见依赖及说明：

依赖	版本	说明
GEOS	v3.3.8+	可选依赖，若涉及地理空间数据处理等相关功能时可能需要
xz-libs	v5.2.0+	必要依赖
squashfs-tools	any	必要依赖
squashfuse	any	可选依赖，用于特定的文件系统相关功能

（四）端口要求

在安装部署前，需确保目标机器的以下端口未被占用且未被防火墙拦截

在安装部署时，也可修改 deploy.cfg 文件中的端口配置参数

端口号	说明
8080	数据库 Web 服务端口，用于通过 Web 界面访问和管理数据库相关操作
26257	数据库服务端口、节点监听端口和对外连接端口，数据库服务进程监听此端口进行数据交互

二、获取安装包

访问 KWDB 的 Gitee 仓库（https://gitee.com/kwdb/kwdb/releases/tag/V2.2.0），根据系统环境下载对应的 DEB 或 RPM 安装包。

例如，如果你的操作系统是基于 Debian 或 Ubuntu 的，应选择 DEB 安装包；若是基于 CentOS 等 Red Hat 系的操作系统，则选择 RPM 安装包。将下载好的安装包复制到待安装 KWDB 的目标机器上，然后解压缩安装包。

解压命令为：

tar -zxvf <package_name>

我这里使用的是 CentOS 7.9，所以解压命令是这样的

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

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

add_user.sh：安装、启动 KWDB 后，用于为 KWDB 数据库创建用户。

deploy.cfg：安装部署配置文件，可在此配置部署节点的 IP 地址、端口等关键信息。

deploy.sh：安装部署脚本，具备安装、卸载、启动、状态获取、关停和重启等多种操作功能。

packages 目录：存放 DEB、RPM 和镜像包。

utils 目录：存放工具类脚本，方便执行一些辅助操作。

monitoring 目录：存放 Prometheus 配置文件、Grafana Dashboard 模板等文件，用于数据库监控和可视化展示相关配置。

三、开始部署

（一）配置 deploy.cfg 文件

登录待部署节点，进入安装包解压后的目录，编辑 deploy.cfg 配置文件。

默认情况下，deploy.cfg 配置文件中包含集群配置参数，对于本地单点部署，需删除或注释 (cluster) 集群配置项。以下是配置文件示例及参数说明：


secure_mode=ymanagement_user=kaiwudbrest_port=8080kaiwudb_port=26257data_root=/var/lib/kaiwudbnode_addr=192.168.64.128ssh_user=admin

secure_mode：是否开启安全模式，默认开启。开启安全模式后，KWDB 生成 TLS 安全证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。若你的使用场景对安全性要求较高，如涉及敏感数据存储和传输，建议保持开启状态；若在测试环境，对安全要求相对较低，也可选择关闭。

management_user：KWDB 的管理用户，默认为 kaiwudb。安装部署后，KWDB 会创建相应的管理用户以及和管理用户同名的用户组。你可以根据实际需求修改为自定义的管理用户名，但要注意用户名的规范性，避免使用特殊字符。

rest_port：KWDB Web 服务端口，默认为 8080。若该端口已被占用，可修改为其他未被占用的端口，修改后在通过 Web 界面访问数据库时，需使用修改后的端口号。

kaiwudb_port：KWDB 服务端口，默认为 26257。同样，若此端口被占用，需进行修改，并确保修改后的端口未被其他服务占用且已在防火墙中开放。

data_root：数据目录，默认为 /var/lib/kaiwudb。数据目录用于存储数据库的数据文件，可根据磁盘空间和数据管理需求，修改为其他合适的目录，如 /data/kaiwudb。修改目录后，需确保该目录有足够的磁盘空间，且部署用户对该目录有读写权限。

node_addr：本地节点对外提供服务的 IP 地址，监听地址为 0.0.0.0，端口为 KWDB 服务端口。如果你的机器有多个 IP 地址，需确保填写的 IP 地址是对外提供服务的正确 IP。若在本地测试环境，可填写 127.0.0.1。

ssh_user：执行 SSH 操作时使用的用户，用于一些远程操作或节点间通信相关的功能（在本地部署中，此参数作用相对较小，但仍需确保填写正确的用户名）。

（二）赋予 deploy.sh 脚本权限

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

chmod +x./deploy.sh

（三）执行单机部署安装命令

执行单机部署安装命令：

./deploy.sh install --single

执行成功后，控制台将输出：

INSTALL COMPLETED: KaiwuDB has been installed successfuly!

（四）启动 KWDB 节点

安装完成后，启动 KWDB 节点，执行命令：

./deploy.sh start

执行成功后，控制台输出：

START COMPLETED: KaiwuDB has started successfuly!

在某些操作系统（如 KylinOS）中，系统可能会提示输入用户密码。此时，无需输入密码，直接按回车键确认即可。

（五）查看 KWDB 节点状态

可通过以下两种方式查看 KWDB 节点状态：

使用 deploy.sh 脚本查看：

./deploy.sh status

使用 systemctl 命令查看（前提是系统支持 systemctl 管理服务）：

systemctl status kaiwudb

若节点正常运行，将显示相应的运行状态信息。

（六）配置 KWDB 开机自启动

为方便使用，可配置 KWDB 开机自启动，这样在系统重启后，KWDB 会自动启动。执行命令：

systemctl enable kaiwudb

四、KWDB 的使用

（一）使用 KaiwuDB 开发者中心连接 KWDB

KaiwuDB 开发者中心是专门为 KWDB 数据库系统量身定制的可视化管理工具，操作便捷，即使是数据库新手也能轻松上手。其功能涵盖数据库连接、数据库管理、模式管理、表管理等多个方面。

依然是从gitee去下载v2.2.0 · KWDB/kwdb - Gitee.com

安装 KaiwuDB 开发者中心

支持操作系统：
Windows 7 及以上 64 位系统
Mac 操作系统（macOS）

不同操作系统版本的界面略有差异，但功能完全相同。

安装步骤：

从kwdb 发行版 - Gitee.com下载安装包并解压缩。解压后的文件目录中，双击运行 KaiwuDB Developer Center.exe 应用程序（Windows 系统）或对应的可执行文件（Mac 系统），即可完成安装。

连接 KWDB 数据库

在首次建立连接或软件中的所有连接都被删除后，软件启动后会自动弹出新建连接向导，引导用户建立连接。其他情况下，如需创建连接，可选择以下任一操作：
单击工具栏或数据库导航区工具栏中的新建连接按钮。
在菜单栏中，单击数据库，然后从下拉菜单中选择新建连接。

以首次建立连接为例，具体连接步骤如下：

在创建新连接窗口，选择 KaiwuDB 驱动，单击下一步
在常规页签，设置主机（填写部署 KWDB 时配置的 node_addr 对应的 IP 地址，若本地部署且使用默认配置，一般为 127.0.0.1）、端口（填写部署时配置的 kaiwudb_port，默认为 26257）、数据库（默认数据库名称，可根据实际创建的数据库名称修改）、用户（填写部署时配置的 management_user，默认为 kaiwudb）和密码（首次使用默认无密码，若开启安全模式且设置了密码，需填写正确密码）
（可选）勾选显示非缺省的数据库，可显示所有数据库。默认情况下，只显示指定连接的数据库
（可选）单击测试链接，检查连接是否成功。连接成功后，将显示相应成功信息
单击确定，数据库导航区将自动更新，显示已连接的数据库

（二）使用 KaiwuDB JDBC 连接 KWDB（适合 Java 开发者）

Java 数据库连接（Java Database Connectivity，JDBC）是 Java 应用程序访问数据库的标准 API。KWDB 提供了 JDBC 驱动程序 KaiwuDB JDBC，支持 Java 应用程序与 KWDB 数据库交互，执行查询、插入、更新和删除等操作。

安装 KaiwuDB JDBC

安装 Java（1.8 及以上版本），可从 Oracle 官方网站（Overview of JDK Installation）获取安装指南并下载安装包进行安装。
安装 Maven（3.6 及以上版本），参考 Apache Maven 官方网站（Installation – Maven）的安装教程进行安装。
安装 KWDB 数据库，并按照上述部署步骤配置好数据库认证方式，创建数据库。
从kwdb 发行版 - Gitee.com获取 KaiwuDB JDBC 驱动包。
运行以下命令，将 KaiwuDB JDBC 安装到本地 Maven 仓库中：

mvn install:install-file "-Dfile=../kaiwudb-jdbc.2.0.4.jar" "-DgroupId=com.kaiwudb" "-DartifactId=kaiwudb-jdbc" "-Dversion=2.0.4" "-Dpackaging=jar"

在项目的 pom.xml 中添加依赖，将 KaiwuDB JDBC 引入到 Java 应用程序中：

<dependency><groupId>com.kaiwudb</groupId><artifactId>kaiwudb-jdbc</artifactId><version>2.0.4</version></dependency>

连接 KWDB 数据库

用户需编写 Java 程序代码来连接数据库。Java 程序代码需要包含以下关键内容：

加载驱动：使用 KWDB 前必须先加载 KWDB 数据库驱动程序类，加载方式如下：

Class.forName("com.kaiwudb.jdbc.Driver");

建立连接：通过 DriverManager.getConnection () 方法与 KWDB 数据库建立连接。KWDB 支持以下连接方式：


Connection conn = DriverManager.getConnection(url);Connection conn = DriverManager.getConnection(url, props);Connection conn = DriverManager.getConnection(url, user, password);

其中，url 为数据库连接地址，格式一般为 jdbc:kaiwudb:// 主机地址：端口号 / 数据库名称；props 为包含连接属性的 Properties 对象；user 为数据库用户名；password 为数据库密码。

通过以上详细的本地部署和使用教程，相信开发者们能够快速将 KWDB 应用到实际项目中，充分发挥其在数据存储、管理与分析方面的强大优势，助力项目高效运行和业务快速发展。

后续我会继续更新更多关于KWDB在实际应用中的文章
敬请期待

本文完