【KWDB 2025创作者计划】面向 AIoT 的分布式多模数据库 KaiwuDB适配之旅
一、业务情况
KaiwuDB 由两部分组成：“Kaiwu”和“DB（DataBase，数据库缩写）”。
Kaiwu
（开务），取自“
开物成务
”，其中“
wu
（物）”亦指“
物联网
”，产品立足于物联网场景，致力于为各行业用户提供稳定安全、高性能、易运维的创新数据软件与服务，一站式满足 AIoT 等场景下数据管理需求及关键行业核心系统的安全可控需求。聚焦工业物联网、数字能源、车联网、智慧产业等快速发展重要领域，均已成功完成落地实践。
KaiwuDB 同时也是一款
分布式、多模融合、支持原生 AI
的数据库产品，支持同一实例同时建立时序库和关系库并融合处理多模数据，具备
千万级设备接入
、
百万级数据秒级写入
、
亿级数据秒级读取
等时序数据高效处理能力，能为各行业用户提供一站式数据存储、管理与分析的基座。致力于打造自主、先进、安全、创新的数据库产品及数据服务平台，大力推动产业融合，充分挖掘数据价值，赋能行业数字化转型升级。
KaiwuDB具备包括多模架构、就地计算、分布式计算、原生 AI 等重点技术。累积获得 20+项自有产品软著、400+项发明专利受理，并完成与100+ 款主流操作系统、CPU、中间件的兼容适配；通过中国信通院可信数据库基础功能、性能、稳定性全项测评、公安部信息系统安全等级保护三级测评；取得 4 项 ISO 认证等。
提供AI+自治，多源异构数据集成、存储、计算、治理和分析服务，支持全域数据资产管理和运营，满足 DCMM 数据管理标准，匹配企事业单位数据湖、数据仓库、数据治理、数据分析、数据资产管理等多样数据管理需求，是企业数据治理、发展数据要素、支撑数据资产入表的有力工具
2.1 、下表列出部署 KWDB 所需的硬件规格
KWDB单节点裸机部署。参考信息如下：
Gitee： https://gitee.com/kwdb/kwdb
https://gitee.com/kwdb/kwdb/releases/tag/V2.2.0
官网文档：
|
项目 |
要求 |
|
CPU 和内存 |
单节点配置建议不低于 4 核 8G。对于数据量大、复杂的工作负载、高并发和高性能场景，建议配置更高的 CPU 和内存资源以确保系统的高效运行。 |
|
磁盘 |
磁盘必须能够实现 500 IOPS 和 30 MB/s 处理效率。 |
|
文件系统 |
建议使用 ext4 文件系统。 |
2.2 、操作系统 KWDB 支持在以下服务器操作系统进行部署
|
操作系统 |
版本 |
架构 |
|
Anolis |
8.6 |
ARM_64 |
|
8.6 |
x86_64 | |
|
KylinOS |
V10 SP3 2403
|
ARM_64 |
|
V10 SP3 2403
|
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 |
1060e |
x86_64 |
|
1060e |
ARM_64 |
|
|
|
|
2.3、 软件依赖
|
依赖 |
版本 |
说明 |
|
OpenSSL |
v1.1.1+ |
N/A |
|
libprotobuf |
v3.6.1+ 3.14.0 |
注意：KylinOS 4.19.90-52.22.v2207 默认的 libprotobuf 版本不满足要求，用户需要提前安装所需版本（推荐 3.6.1 和 3.14.0）。 |
|
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 |
可选依赖 |
2.4、端口 要求
下表列出 KWDB 服务需要映射的端口。在安装部署前，确保目标机器的以下端口没有被占用且没有被防火墙拦截。在安装部署时，用户可以修改 deploy.cfg 文件中的端口配置参数。
|
端口号 |
说明 |
|
8080 |
数据库 Web 服务端口 |
|
26257 |
数据库服务端口、节点监听端口和对外连接端口 |
2.5、 安装 包
获取系统环境对应的 DEB 或 RPM 安装包，将安装包复制到待安装 KWDB 的目标机器上，然后解压缩安装包：
tar -zxvf <package_name>
复制 | sh 解压后生成的目录包含以下文件：
|
文件 |
说明 |
|
add_user.sh |
安装、启动 KWDB 后，为 KWDB 数据库创建用户。hhlkwdb |
|
deploy.cfg |
安装部署配置文件，用于配置部署节点的 IP 地址、端口等配置信息。 |
|
deploy.sh |
安装部署脚本，用于安装、卸载、启动、状态获取、关停和重启等操作。 |
|
packages 目录 |
存放 DEB、RPM 和镜像包。 |
|
utils 目录 |
存放工具类脚本。 |
|
|
|
部署 KWDB 时，系统将对配置文件、运行环境、硬件配置和软件依赖进行检查。如果相应硬件未能满足要求，系统将继续安装，并提示硬件规格不满足要求。如果软件依赖未能满足要求，系统将中止安装，并提供相应的提示信息。
在部署过程中，系统会自动生成相关日志。如果部署时出现错误，用户可以通过查看终端输出或 KWDB 安装目录中 log 目录里的日志文件，获取详细的错误信息。
部署完成后，系统会将 KWDB 封装成系统服务（名称为 kaiwudb），并生成以下文件：
· kaiwudb.service：配置 KWDB 的 CPU 资源占用率。
· kaiwudb_env：配置 KWDB 启动参数。
[root@ axdmkaiwudb data]# cd kwdb_install/
解压后生成的目录包含以下文件：
tree -N
├── add_user.sh ## 安装、启动 KWDB 后，为 KWDB 数据库创建用户
├── deploy.cfg ## 安装部署配置文件，用于配置部署节点的 IP 地址、端口等配置信息
├── deploy.sh ## 安装部署脚本，用于安装、卸载、启动、状态获取、关停和重启等操作
├── packages ## 存放 DEB 、 RPM 和镜像包
│ ├── kwdb-libcommon-2.1.0-kylin.ky10.x86_64.rpm
│ └── kwdb-server-2.1.0-kylin.ky10.x86_64.rpm
└── utils ## 存放工具类脚本
├── container_shell.sh
├── kaiwudb_cluster.sh
├── kaiwudb_common.sh
├── kaiwudb_hardware.sh
├── kaiwudb_install.sh
├── kaiwudb_log.sh
├── kaiwudb_operate.sh
├── kaiwudb_uninstall.sh
├── kaiwudb_upgrade.sh
├── process_bar.sh
└── utils.sh
如需配置 KWDB，遵循以下步骤：
1、登录待配件节点，编辑安装包目录下的 deploy.cfg 配置文件，设置安全模式、管理用户、服务端口等信息。
2、说明
默认情况下，deploy.cfg 配置文件中包含集群配置参数。请删除或注释 [cluster] 集群配置项。
配置文件示例：
[global]
# Whether to turn on secure mode
#secure_mode=insecure
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=/var/lib/kaiwudb
# CPU usage[0-1]
# cpu=1
[local]
# local node configuration
node_addr=10.13.4.45
# 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
参数说明：
l global：全局配置
n insecure：使用非安全模式。
n tls：（默认选项）开启 TLS 安全模式。开启安全模式后，KaiwuDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证，生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
n secure_mode：是否开启安全模式，支持以下两种取值：
n management_user：KaiwuDB 的管理用户，默认为 kaiwudb。安装部署后，KaiwuDB 创建相应的管理用户以及和管理用户同名的用户组。
n rest_port：KaiwuDB Web 服务端口，默认为 8080。
n kaiwudb_port：KaiwuDB 服务端口，默认为 26257。
n data_root：数据目录，默认为 /var/lib/kaiwudb。 cpu: 可选参数，用于指定 KaiwuDB 服务占用当前节点服务器 CPU 资源的比例，默认无限制。取值范围为 [0,1]，最大精度为小数点后两位。
l local：本地节点配置
n node_addr：本地节点对外提供服务的 IP 地址，监听地址为 0.0.0.0，端口为 KaiwuDB 服务端口。
l 建议关闭防火墙：
[root@axdmkaiwudb ~]# systemctl stop firewalld.service
[root@ ~]# systemctl disable firewalld.service
Removed /etc/systemd/system/multi-user.target.wants/firewalld.service.
Removed /etc/systemd/system/dbus-org.fedoraproject.FirewallD1.service.
l 关闭SELinux
sed -i 's/^SELINUX=enforcing$/SELINUX=disabled/' /etc/selinux/config
setenforce 0
[reboot]
l 配置hosts文件
cat >>/etc/hosts<<EOF
10.13.4.45 axdmkaiwudb
EOF
创建用户
l useradd kaiwudb
echo "Kwdb#Kwdb " | passwd --stdin kaiwudb
tar -xzf protobuf-cpp-3.14.0.tar.gz
cd protobuf-3.14.0
./configure --prefix=/usr/local/protobuf
make -j$(nproc)
sudo make install
echo "export LD_LIBRARY_PATH=/usr/local/protobuf/lib" >> ~/.bashrc
source ~/.bashrc
### **3. 验证安装**
```bash
protoc --version
```
[root@axdmkaiwudb kwdb_install]# ./deploy.sh install --single
[ERROR] 2025-04-17 11:10:08 Install failed: warning: ./kwdb-libcommon-2.2.0-kylin.ky10.x86_64.rpm: Header V4 RSA/SHA256 Signature, key ID ddf7c8ca: NOKEY error: Failed dependencies: protobuf >= 3.5.0 is needed by kwdb-libcommon-2.2.0-kylin.ky10.x86_64
[root@axdmkaiwudb kwdb_install]#
yum -y install protobuf geos
[root@axdmkaiwudb kwdb_install]# ./deploy.sh install --single
[root@axdmkaiwudb kwdb_install]# ls
add_user.sh deploy.cfg deploy.cfgbak deploy.sh kaiwudb_certs.tar.gz log packages utils
[root@axdmkaiwudb kwdb_install]# ./deploy.sh start
[START COMPLETED]:KaiwuDB start successfully.
[root@axdmkaiwudb kwdb_install]# ps
PID TTY TIME CMD
56859 pts/0 00:00:00 bash
79605 pts/0 00:00:00 deploy.sh
81125 pts/0 00:00:00 ps
[root@axdmkaiwudb kwdb_install]# ./deploy.sh status
[STATUS COMPLETED]:KaiwuDB is runnning now.
[root@axdmkaiwudb kwdb_install]# systemctl enable kaiwudb
[root@axdmkaiwudb data]# kwbase sql --host=10.13.4.45:26257 --certs-dir=/etc/kaiwudb/certs
#
# 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: b5ab43ee-2623-4097-9bb4-05419a82dc01
#
# Enter \? for a brief introduction.
#
root@10.13.4.45:26257/defaultdb>
root@10.13.4.45:26257/defaultdb> show database;
database
-------------
defaultdb
(1 row)
Time: 850.704µs
root@10.13.4.45:26257/defaultdb> CREATE TS DATABASE tsdb RETENTIONS 180d;
CREATE TS DATABASE
Time: 5.624826ms
root@10.13.4.45:26257/defaultdb> show database;
database
-------------
defaultdb
(1 row)
Time: 1.096633ms
root@10.13.4.45:26257/defaultdb> SHOW DATABASES;
database_name | engine_type
----------------+--------------
defaultdb | RELATIONAL
postgres | RELATIONAL
system | RELATIONAL
tsdb | TIME SERIES
(4 rows)
Time: 1.794712ms
root@10.13.4.45:26257/defaultdb> USE tsdb;
SET
Time: 723.505µs
root@10.13.4.45:26257/tsdb> CREATE USER testu;
GRANT ALL ON DATABASE tsdb to testu;
SHOW USERS;
CREATE USER
Time: 5.363381ms
GRANT
Time: 3.430742ms
username | options | member_of
-----------+------------+------------
admin | CREATEROLE | {}
root | CREATEROLE | {admin}
testu | | {}
(3 rows)
Time: 3.621801ms
root@10.13.4.45:26257/tsdb>
root@10.13.4.45:26257/tsdb>
root@10.13.4.45:26257/tsdb> CREATE TABLE tsdb.readings (
ts timestamp NOT NULL, -- 数据读取时间戳
temperature FLOAT, -- 温度（摄氏度）
humidity FLOAT -- 湿度（百分比）
) TAGS (
sensor_id INT NOT NULL, -- 传感器 ID
location CHAR(256) NOT NULL -- 传感器位置（如 "Room 101"）
) PRIMARY TAGS(sensor_id);
CREATE TABLE
Time: 61.467038ms
root@10.13.4.45:26257/tsdb> INSERT INTO tsdb.readings
VALUES
(NOW(), 23.0, 59.5, 101, 'Room 101'),
(NOW(), 23.5, 58.9, 102, 'Room 102'),
(NOW(), 19.8, 65.5, 103, 'Room 103');
INSERT 3
Time: 7.002598ms
root@10.13.4.45:26257/tsdb>
root@10.13.4.45:26257/tsdb> SELECT * FROM readings;
ts | temperature | humidity | sensor_id | location
--------------------------------+-------------+----------+-----------+-----------
2025-04-17 03:45:31.741+00:00 | 23.5 | 58.9 | 102 | Room 102
2025-04-17 03:45:31.741+00:00 | 19.8 | 65.5 | 103 | Room 103
2025-04-17 03:45:31.741+00:00 | 23 | 59.5 | 101 | Room 101
(3 rows)
Time: 3.693225ms
root@10.13.4.45:26257/tsdb> SHOW CREATE TABLE readings;
table_name | create_statement
-------------+------------------------------------------------------------
readings | CREATE TABLE readings (
| ts TIMESTAMPTZ(3) NOT NULL,
| temperature FLOAT8 NULL,
| humidity FLOAT8 NULL
| ) TAGS (
| sensor_id INT4 NOT NULL,
| location CHAR(256) NOT NULL ) PRIMARY TAGS(sensor_id)
| retentions 15552000s
| activetime 1d
| partition interval 10d
(1 row)
Time: 191.10711ms
root@10.13.4.45:26257/tsdb>
[root@axdmkaiwudb kwdb_install]# ./add_user.sh
Please enter the username:hhlkwdb
Please enter the password:
[ADD USER COMPLETED]:User creation completed.
[root@axdmkaiwudb kwdb_install]#
[root@axdmkaiwudb kwdb_install]# kwbase sql --certs-dir=/etc/kaiwudb/certs/ --host=10.13.4.45 -u hhlkwdb
#
# Welcome to the KWDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
Enter password:
# 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: b5ab43ee-2623-4097-9bb4-05419a82dc01
#
# Enter \? for a brief introduction.
#
hhlkwdb@10.13.4.45:26257/defaultdb> show database;
database
-------------
defaultdb
(1 row)
Time: 841.53µs
hhlkwdb@10.13.4.45:26257/defaultdb> SHOW DATABASES;
database_name | engine_type
----------------+--------------
defaultdb | RELATIONAL
postgres | RELATIONAL
system | RELATIONAL
tsdb | TIME SERIES
(4 rows)
Time: 1.582383ms
hhlkwdb@10.13.4.45:26257/defaultdb> SHOW tables
-> ;
table_name | table_type
-------------+-------------
(0 rows)
Time: 2.042955ms
hhlkwdb@10.13.4.45:26257/defaultdb>
KWDB还提供了一个可视化界面的开发者中心（KaiwuDB Developer Center，下简称KWDC），这里下载了一个Windows版的：
虽然官方文档要求了OpenJRE 8及以上版本但是包里面是已经集成了JRE，不需要单独安装。
打开KWDC就弹出了“创建新链接”的页面，这里尝试将数据库的连接加入：
选择KaiwuDB驱动 配置连接信息并测试
测试成功后点击完成即可。
这里简单功能性测试了。
- 官方文档小问题比较多，包括但不限于内容错误、表达不明确或未提醒等，希望检查并修正
- 安装包适配系统覆盖不足，最重要的是连列表中的都没覆盖完
- 在比较重要的操作系统配置，没有明确说明
完成了KWDB单节点裸机部署，并完成了连接即简单测试。官方文档和安装文件还是有不少小纰漏，希望进行修改优化、改进。
来自 “ ITPUB博客 ” ，链接：https://blog.itpub.net/69923890/viewspace-3081658/ ，如需转载，请注明出处，否则将追究法律责任。
