原文链接：【KWDB 2025创作者计划】面向 AIoT 的分布式多模数据库 KaiwuDB适配之旅_ITPUB博客

作者：u_6c1e5be21fad

一、业务情况

  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

官网文档：

https://www.kaiwudb.com/kaiwudb_docs/#/oss_v2.2.0/quickstart/install-kaiwudb/quickstart-bare-metal.html

2.2 、操作系统 KWDB 支持在以下服务器操作系统进行部署

2.3、 软件依赖

2.4、端口 要求

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

2.5、 安装包

获取系统环境对应的 DEB 或 RPM 安装包，将安装包复制到待安装 KWDB 的目标机器上，然后解压缩安装包：

tar -zxvf <package_name>

复制 | sh 解压后生成的目录包含以下文件：

部署 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

创建用户

  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;
ｇｒａｎｔ ALL ON DATABASE tsdb to testu;
SHOW USERS;
CREATE USER
 
Time: 5.363381ms
 
ｇｒａｎｔ
 
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 ｃｈａｒ(256) NOT NULL    -- 传感器位置（如 "Room 101"）
) PRIMARY TAGS(sensor_id);
 
CREATE TABLE
 
Time: 61.467038ms
 
root@10.13.4.45:26257/tsdb> ｉｎｓｅｒｔ 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');
 
ｉｎｓｅｒｔ 3
 
Time: 7.002598ms
 
root@10.13.4.45:26257/tsdb>
root@10.13.4.45:26257/tsdb>  ｓｅｌｅｃｔ * 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 ｃｈａｒ(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单节点裸机部署，并完成了连接即简单测试。官方文档和安装文件还是有不少小纰漏，希望进行修改优化、改进。