原文链接：【KWDB 2025 创作者计划】_KWDB单机部署的坑都踩遍了_ITPUB博客

作者：WDDWR7307914

KWDB 是由开放原子开源基金会孵化及运营的开源项目，是一款面向 AIoT 场景的分布式多模数据库产品，支持在同一实例同时建立时序库和关系库并融合处理多模数据，具备千万级设备接入、百万级数据秒级写入、亿级数据秒级读取等时序数据高效处理能力，具有稳定安全、高可用、易运维等特点。

接下里就带大家大家一起部署下，并总结了一些坑，希望帮助到大家！

1.ubuntu系统安装

https://ubuntu.com/download/desktop
若官网下载速度较慢，可使用国内镜像站：
mirrors.163.com/ubuntu-releases
mirrors.aliyun.com
amd64表示该镜像基于x86-64架构（即64位扩展的x86指令集）
--修改root密码，beijing
sudo passwd root
--避坑：如果你无法SSH远程就用以下方式解决：
# 安装并重启SSH
sudo apt install openssh-server && sudo systemctl restart ssh
sudo apt install net-tools
vi /etc/ssh/sshd_config
PermitRootLogin yes
sudo systemctl restart ssh

2.资源包下载

所需资源包下载地址：
https://gitee.com/kwdb/kwdb/releases/tag/V2.2.0
tar -xzvf KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz
kwdb_install/
kwdb_install/deploy.sh
kwdb_install/add_user.sh
kwdb_install/.construction_var
kwdb_install/deploy.cfg
kwdb_install/packages/
kwdb_install/packages/kwdb-server_2.2.0-ubuntu-22.04_amd64.deb
kwdb_install/packages/.version
kwdb_install/packages/kwdb-libcommon_2.2.0-ubuntu-22.04_amd64.deb
kwdb_install/utils/
kwdb_install/utils/kaiwudb_upgrade.sh
kwdb_install/utils/kaiwudb_operate.sh
kwdb_install/utils/kaiwudb_log.sh
kwdb_install/utils/utils.sh
kwdb_install/utils/kaiwudb_install.sh
kwdb_install/utils/kaiwudb_cluster.sh
kwdb_install/utils/process_bar.sh
kwdb_install/utils/kaiwudb_common.sh
kwdb_install/utils/container_shell.sh
kwdb_install/utils/kaiwudb_hardware.sh
kwdb_install/utils/kaiwudb_uninstall.sh

3.安装部署

3.1 配置文件修改

编辑安装包目录下的 deploy.cfg 配置文件,请删除或注释 [cluster] 集群配置项
cd kwdb_install
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.3.10
参数说明：
global：全局配置
secure_mode：是否开启安全模式，支持以下两种取值：
insecure：使用非安全模式。
tls：（默认选项）开启 TLS 安全模式。开启安全模式后，KWDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
management_user：KWDB 的管理用户，默认为 kaiwudb。安装部署后，KWDB 创建相应的管理用户以及和管理用户同名的用户组。
rest_port：KWDB Web 服务端口，默认为 8080。
kaiwudb_port：KWDB 服务端口，默认为 26257。
data_root：数据目录，默认为 /var/lib/kaiwudb。
cpu: 可选参数，用于指定 KWDB 服务占用当前节点服务器 CPU 资源的比例，默认无限制。取值范围为 [0,1]，最大精度为小数点后两位。注意：如果部署环境为 Ubuntu 18.04 版本，部署集群后，需要将 kaiwudb.service 文件中的 CPUQuota 修改为整型值，例如，将 180.0% 修改为 180%，以确保设置生效。具体操作步骤，参见配置 CPU 资源占用率。
local：本地节点配置
node_addr：本地节点对外提供服务的 IP 地址，监听地址为 0.0.0.0，端口为 KWDB 服务端口。

3.2 正式安装

1.安装依赖
sudo apt ｕｐｄａｔｅ
sudo apt install cmake
sudo snap install go --classic
chmod +x ./deploy.sh
./deploy.sh install --single
避坑点：如果以下报错记得安装依赖：
sudo apt install libprotobuf-dev
/kwdb-server_2.2.0-ubuntu-22.04_amd64.deb ... 
Unpacking kwdb-server (2.2.0-ubuntu-22.04) ... 
dpkg: dependency problems prevent configuration of 
kwdb-server: kwdb-server depends on libprotobuf23 (>= 3.12.4); however:

3.3 启动数据库

./deploy.sh start
systemctl start kaiwudb
systemctl status kaiwudb
配置 KWDB 开机自启动
systemctl enable kaiwudb

4.使用数据库

--连接数据库
kwbase sql --insecure --host=192.168.3.10
#
# 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:02, go1.16.15, gcc 11.4.0) (same version as client)
# Cluster ID: 78410d1d-1cbf-4cdd-b533-9b3e0dc57275
#
# Enter \? for a brief introduction.
#
root@192.168.3.10:26257/defaultdb> show database;
  database
-------------
  defaultdb
(1 row)
Time: 792.828µs
root@192.168.3.10:26257/defaultdb> show users;
  username |  options   | member_of
-----------+------------+------------
  admin    | CREATEROLE | {}
  root     | CREATEROLE | {admin}
(2 rows)
Time: 3.100796ms
避坑点：如果登陆有如下报错
KWDB Error: You must install at least one postgresql-client-<version> package
KWDB Error: You must install at least one postgresql-client-<version> package
# Ubuntu/Debian/KylinOS
sudo apt-get install postgresql-client
# CentOS/KylinOS
sudo yum install postgresql
登陆方式：
psql -U test -h 127.0.0.1 -p 26257 -d iot

KWDB 的时序数据库（Timeseries Database）和关系型数据库（Relational Database）使用不同的存储引擎和元数据管理方式
时序数据库：专门存储带时间戳的序列化数据，要求表结构包含主时间戳字段和标签字段
关系型数据库：支持传统关系模型，可定义主键、外键、索引等约束，适用于非时间序列数据

4.1 时序数据库

默认情况下，root 用户具有 Admin 角色。创建成功后，用户拥有该数据库的全部权限
CREATE TS DATABASE ts_db;
创建一个名为 iot 的数据库，并将数据库的生命周期和分区时间范围分别设置为 50d 和 2d
CREATE TS DATABASE iot RETENTIONS 50d PARTITION INTERVAL 2d;
SHOW DATABASES WITH COMMENT;
  database_name | engine_type | comment
----------------+-------------+----------
  defaultdb     | RELATIONAL  | NULL
  iot           | TIME SERIES | NULL
  postgres      | RELATIONAL  | NULL
  system        | RELATIONAL  | NULL
  ts_db         | TIME SERIES | NULL
  
以下示例将 ts_db 数据库设置为当前数据库
USE ts_db;
创建用户
CREATE USER test;
ｇｒａｎｔ ALL ON DATABASE iot to test;
SHOW USERS;
kwbase sql --insecure -u test -d iot
CREATE TABLE sensor_data (
  ts timestamptz NOT NULL,
  temperature FLOAT
) TAGS (
  device_id INT NOT NULL,
  region VARCHAR(6)
) PRIMARY TAGS (device_id);
-- 单条数据插入
ｉｎｓｅｒｔ INTO sensor_data (ts, temperature, device_id, region)
VALUES (
  '2025-04-11 14:30:00.000', 
  24.5, 
  1001, 
  'zoneA'
);
-- 批量插入
ｉｎｓｅｒｔ INTO sensor_data VALUES
  ('2025-04-11 14:35:00', 25.0, 1002, 'zoneB'),
  ('2025-04-11 14:40:00', 23.8, 1003, 'zoneA');
  
  
-- 查询数据（利用主标签索引加速）
ｓｅｌｅｃｔ * FROM sensor_data 
WHERE device_id = 1001 
AND ts BETWEEN '2025-04-11' AND '2025-04-12';
SHOW TABLES FROM iot;
SHOW CREATETABLE sensor_data;

4.2 关系型数据库

# 从普通用户切换至 kaiwudb 管理员账户（需 sudo 权限）
sudo su - kaiwudb
通过 SQL 切换数据库账户（需提前创建用户并授权）：
-- 使用默认管理员连接（示例参数）
sudo apt-get install postgresql-client
psql -U test -h 127.0.0.1 -p 26257 -d iot
kwbase sql --insecure --host=192.168.3.10
CREATE DATABASE business_db;
USE business_db;
CREATE TABLE users (
  id INT8 DEFAULT unique_rowid() PRIMARY KEY,
  name VARCHAR(50) NOT NULL,
  email VARCHAR(100) UNIQUE
);

5.技术破局

关系与时序的“无缝混搭”，传统数据库的痛点在于多源异构数据割裂管理——时序数据存InfluxDB，关系数据用MySQL，业务逻辑被迫在多个系统间“反复横跳”。

而KWDB通过自适应多模引擎，将时序库与关系库整合为统一实例

性能碾压：千万级设备接入、百万级数据秒级写入，基于“就地计算”技术减少90%跨系统数据迁移开销；

成本锐减：通过Delta-Zip跨模压缩算法，存储空间节省90%，冷热数据自动分层降低TCO3。

开发简化：统一SQL接口同时作时序与关系数据，DBA无需再为多库协同开发头疼