【KWDB 2025 创作者计划】_轻松搞定！KaiwuDB单节点裸机部署（二进制安装包版）

一、KaiwuDB数据库核心功能

1.1、KaiwuDB产品介绍

KaiwuDB是面向实时分析的高性能分布式数据库，具备以下核心特性：

• 混合负载处理（HTAP） 支持事务型（OLTP）与分析型（OLAP）混合负载，单引擎实现毫秒级实时分析。
• 内置分布式事务管理，保证ACID特性。 时序数据优化 专为物联网场景设计，支持时间分区、降采样、数据自动压缩（压缩率可达10:1）。
• 提供time_bucket等时序函数，简化时间窗口分析。

云原生架构

• 支持Kubernetes部署，自动扩缩容，多副本高可用（RPO=0，RTO<30秒）。
• 存储计算分离设计，兼容对象存储（如S3、OSS）。

多协议兼容

• 兼容PostgreSQL协议（支持JDBC/ODBC），可直接使用Pg生态工具（如pgAdmin）。
• 提供类MongoDB的文档存储接口（实验性功能）。

1.2、产品架构

相比传统的数据库，KaiwuDB 提供多模数据管理能力，支持不同数据模型的统一存储，助力企业跨部门、跨业务统一管理数据，实现多业务数据融合，支撑多样化的应用服务。KaiwuDB 的产品架构如下图所示：

• 数据存储：采用行列混存架构，支持固态硬盘、机械硬盘等各类存储设备。
• 数据副本：采用 Shared Nothing 架构，基于 Raft 协议的高可用、多副本架构，支持数据均衡及容错，保障数据服务不中断。
• 执行计算：融合多种数据计算引擎，根据不同模型数据特征选择不同的存储、计算模式，对外提供统一的接口，提供多种分析计算能力，提升查询效率。
  自适应时序引擎：支持多种时序数据特色的复杂查询和多维聚合方式。与传统关系数据库相比，KaiwuDB 具备优异的查询性能。另外，KaiwuDB 提供 5-30 倍的压缩能力，数据压缩后无需解压缩即可使用。
  事务处理引擎：支持分布式事务和 MVCC（Multi-Version Concurrency Control，多版本并发控制），具备注释、视图、约束、索引、序列等功能。
  预测分析引擎：提供模型生命周期管理、模型训练、模型推理预测等功能。任何拥有数据库应用开发背景的开发人员都可以轻松地完成模型管理和预测等操作。
• 系统管理：提供系统连接、身份认证、权限管理、资源管理等多种系统管理方式。
• 生态工具与兼容：提供数据库操作、监控管理等可视化工具，兼容 EMQX、Kafka、Telegraf 等第三方工具。

二、环境准备

2.1、硬件

下表列出部署 KaiwuDB 所需的硬件规格。

2.2、操作系统

KaiwuDB 支持在以下服务器操作系统进行安装部署。

说明

未提及的操作系统版本也许可以运行 KaiwuDB，但尚未得到 KaiwuDB 官方支持。

2.3、软件依赖

安装时，KaiwuDB 会对依赖进行检查。如果缺少依赖会退出安装并提示依赖缺失。如果目标机器不能联网，用户需要在能联网的机器上根据目标机器的操作系统下载好所有依赖文件，然后将依赖文件复制到目标机器上进行安装。

下表列出需要在目标机器安装的依赖：

2.4、端口要求

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

2.5、主机信息

[root@KWDBServer1 ~]# hostnamectl
   Static hostname: KWDBServer1
         Icon name: computer-vm
           Chassis: vm
        Machine ID: 0f88fab206ec46ebbef8b4954762d5dc
           Boot ID: cd8d09626e794619b6bd6d059c51014c
    Virtualization: vmware
  Operating System: Kylin Linux Advanced Server V10 (Halberd)
            Kernel: Linux 4.19.90-89.11.v2401.ky10.x86_64
      Architecture: x86-64
[root@KWDBServer1 ~]#

2.6、内存信息

[root@KWDBServer1 ~]# free -h
              total        used        free      shared  buff/cache   available
Mem:          6.5Gi       705Mi       5.4Gi       9.0Mi       386Mi       5.6Gi
Swap:         8.0Gi          0B       8.0Gi
[root@KWDBServer1 ~]#

2.7、CPU信息

[root@KWDBServer1 ~]# lscpu
架构：                              x86_64
CPU 运行模式：                      32-bit, 64-bit
字节序：                            Little Endian
Address sizes:                      45 bits physical, 48 bits virtual
CPU:                                4
在线 CPU 列表：                     0-3
每个核的线程数：                    1
每个座的核数：                      1
座：                                4
NUMA 节点：                         1
厂商 ID：                           GenuineIntel
BIOS Vendor ID:                     GenuineIntel
CPU 系列：                          6
型号：                              154
型号名称：                          12th Gen Intel(R) Core(TM) i7-12650H
BIOS Model name:                    12th Gen Intel(R) Core(TM) i7-12650H

2.8、硬盘空间

[root@KWDBServer1 ~]# lsblk
NAME        MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
sr0          11:0    1  4.4G  0 rom
nvme0n1     259:0    0  200G  0 disk
├─nvme0n1p1 259:1    0  300M  0 part /boot
├─nvme0n1p2 259:2    0  100G  0 part /home
├─nvme0n1p3 259:3    0 91.7G  0 part /
├─nvme0n1p4 259:4    0    1K  0 part
└─nvme0n1p5 259:5    0    8G  0 part [SWAP]
[root@KWDBServer1 ~]#

2.9、开启防火墙

[root@KWDBServer1 ~]# firewall-cmd --zone=public --add-port=8080/tcp --permanent
success
[root@KWDBServer1 ~]# firewall-cmd --zone=public --add-port=26257/tcp --permanent
success
[root@KWDBServer1 ~]# firewall-cmd --reload
success
[root@KWDBServer1 ~]#

2.10、检查主机时间

[root@KWDBServer1 ~]# date
2025年 04月 08日 星期二 11:41:16 CST
[root@KWDBServer1 ~#

2.11、安装扩展

[root@KWDBServer1 ~]# yum install -y openssl protobuf geos* xz-libs squashfs-tools wget
Last metadata expiration check: 0:07:06 ago on 2025年04月08日 星期二 11时36分46秒.
Package openssl-1:1.1.1f-31.p23.ky10.x86_64 is already installed.
Package xz-libs-5.2.5-3.ky10.x86_64 is already installed.
------------------------------------
------------------------------------
------------------------------------

Installed:
  geos-3.6.1-12.ky10.x86_64           geos-devel-3.6.1-12.ky10.x86_64           protobuf-3.14.0-7.ky10.x86_64

Complete!
[root@KWDBServer1 ~]#

2.12、创建文件上传目录

[root@KWDBServer1 ~]# mkdir /kwdb
[root@KWDBServer1 ~]#

三、KWDB部署

3.1、下载地址

https://gitee.com/kwdb/kwdb/releases

3.2、在线下载安装包

[kaiwudb@KWDBServer1 root]$  cd /kwdb/

[root@KWDBServer1 kwdb]# wget https://gitee.com/kwdb/kwdb/releases/download/V2.2.0/KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz
--2025-04-08 11:47:07--  https://gitee.com/kwdb/kwdb/releases/download/V2.2.0/KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz
正在解析主机 gitee.com (gitee.com)... 180.76.199.13, 180.76.198.225, 180.76.198.77
正在连接 gitee.com (gitee.com)|180.76.199.13|:443... 已连接。
已发出 HTTP 请求，正在等待回应... 302 Found
位置：https://gitee.com/kwdb/kwdb/attach_files/2130400/download/KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz [跟随至新的 URL]
--2025-04-08 11:47:07--  https://gitee.com/kwdb/kwdb/attach_files/2130400/download/KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz
再次使用存在的到 gitee.com:443 的连接。
已发出 HTTP 请求，正在等待回应... 302 Found
位置：https://foruda.gitee.com/attach_file/1743423049598005740/kwdb-2.2.0-kylinv10_2403-x86_64-rpms.tar.gz?token=c906e15d3c4bf09e0a68e393d780a3ca&ts=1744084028&attname=KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz [跟随至新的 URL]
--2025-04-08 11:47:08--  https://foruda.gitee.com/attach_file/1743423049598005740/kwdb-2.2.0-kylinv10_2403-x86_64-rpms.tar.gz?token=c906e15d3c4bf09e0a68e393d780a3ca&ts=1744084028&attname=KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz
正在解析主机 foruda.gitee.com (foruda.gitee.com)... 180.76.199.13, 180.76.198.77
正在连接 foruda.gitee.com (foruda.gitee.com)|180.76.199.13|:443... 已连接。
已发出 HTTP 请求，正在等待回应... 200 OK
长度：29046637 (28M) [application/gzip]
正在保存至: “KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz”

KWDB-2.2.0-kylinV10_2403-x86_ 100%[=================================================>]  27.70M   533KB/s  用时 55s

2025-04-08 11:48:04 (514 KB/s) - 已保存 “KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz” [29046637/29046637])

[root@KWDBServer1 kwdb]#

[root@KWDBServer1 kwdb]# ll
总用量 28368
-rw-r--r-- 1 root root 29046637  4月  8 11:48 KWDB-2.2.0-kylinV10_2403-x86_64-rpms.tar.gz
[root@KWDBServer1 kwdb]#

3.3、解压安装包

[kaiwudb@KWDBServer1 kwdb]$ tar xzvf KWDB-2.2.0-kylinV10_2403-x86_64-rpms.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/.version
kwdb_install/packages/kwdb-server-2.2.0-kylin.ky10.x86_64.rpm
kwdb_install/packages/kwdb-libcommon-2.2.0-kylin.ky10.x86_64.rpm
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
aiwudb@KWDBServer1 kwdb]$

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

3.4、修改配置文件deploy.cfg

[kaiwudb@KWDBServer1 kwdb]$ cd kwdb_install/
[kaiwudb@KWDBServer1 kwdb_install]$ vi deploy.cfg

说明：注释deploy.cfg中的[cluster]以下内容

注释：# [cluster]
# remote node addr,split by ','
# node_addr=127.0.0.2,127.0.0.3
# ssh info
# ssh_port=22
# ssh_user=admin

修改内容如下：

[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=/var/lib/kaiwudb
# CPU usage[0-1]
# cpu=1
[local]
# local node configuration
node_addr=0.0.0.0
# 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

参数说明：

• global：全局配置
• secure_mode：是否开启安全模式，支持以下三种取值：
• insecure：使用非安全模式。
• tls：（默认选项）开启 TLS 安全模式。开启安全模式后，KaiwuDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
• tlcp：开启 TLCP 安全模式。开启安全模式后，KaiwuDB 生成 TLCP 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
• management_user：KaiwuDB 的管理用户，默认为 kaiwudb。安装部署后，KaiwuDB 创建相应的管理用户以及和管理用户同名的用户组。
• rest_port：KaiwuDB Web 服务端口，默认为 8080。
• kaiwudb_port：KaiwuDB 服务端口，默认为 26257。
• data_root：数据目录，默认为 /var/lib/kaiwudb。
• cpu: 可选参数，用于指定 KaiwuDB 服务占用当前节点服务器 CPU 资源的比例，默认无限制。取值范围为 [0,1]，最大精度为小数点后两位。注意：如果部署环境为 Ubuntu 18.04 版本，部署完成后，需要将 kaiwudb.service 文件中的 CPUQuota 修改为整型值，例如，将 180.0% 修改为 180%，以确保设置生效。具体操作步骤，参见配置 CPU 资源占用率。
• encrypto_store: 可选参数，用于在部署时启用关系数据库存储加密功能。默认情况下，该参数不会显示，需要用户手动添加到配置文件中并设置为 true。启用后，系统将在 /etc/kaiwudb/certs 目录下自动生成存储密钥，使用 SM4 加密算法对数据进行加密。KaiwuDB 支持通过 --store-encryption 启动参数，在部署后进行目录加密、解密、存储密钥更新和算法更换等操作，更多信息，参见存储加密。
• local：本地节点配置
• node_addr：本地节点对外提供服务的 IP 地址，监听地址为 0.0.0.0，端口为 KaiwuDB 服务端口。

3.5、为 deploy.sh 脚本添加运行权限

[root@KWDBServer1 kwdb_install]# chmod +x ./deploy.sh

3.6、执行单机部署安装命令

[root@KWDBServer1 kwdb_install]#
[root@KWDBServer1 kwdb_install]# ./deploy.sh install --single
                                                                                                                         [WARN] 2025-04-08 11:51:25 The number of CPU cores does not meet the requirement. KaiwuDB may running failed.
Please input kaiwudb's password:                                                                                                                                                                                                                [INSTALL COMPLETED]:KaiwuDB has been installed successfully! To start KaiwuDB, please execute the command 'systemctl daemon-reload'.
[root@KWDBServer1 kwdb_install]#

3.7、重新加载 systemd 守护进程的配置文件

[root@KWDBServer1 kwdb_install]#
[root@KWDBServer1 kwdb_install]# systemctl daemon-reload
[root@KWDBServer1 kwdb_install]#

3.8、启动 KaiwuDB 节点

[root@KWDBServer1 kwdb_install]# ./deploy.sh start
[START COMPLETED]:KaiwuDB start successfully.
[root@KWDBServer1 kwdb_install]#

3.9、查看 KaiwuDB 节点状态

[root@KWDBServer1 kwdb_install]# ./deploy.sh status
[STATUS COMPLETED]:KaiwuDB is runnning now.
[root@KWDBServer1 kwdb_install]#

或者

[root@KWDBServer1 kwdb_install]# systemctl status kaiwudb
● kaiwudb.service - KaiwuDB Service
   Loaded: loaded (/etc/systemd/system/kaiwudb.service; enabled; vendor preset: disabled)
   Active: active (running) since Tue 2025-04-08 11:51:46 CST; 23s ago
 Main PID: 27530 (kwbase)
    Tasks: 40
   Memory: 458.3M
   CGroup: /system.slice/kaiwudb.service
           └─27530 /usr/local/kaiwudb/bin/kwbase start-single-node --certs-dir=/etc/kaiwudb/certs --listen-addr=0.0.0.0>

4月 08 11:51:49 KWDBServer1 kwbase[27530]: sql:                 postgresql://root@192.168.40.201:26257?sslcert=%2Fetc%2>
4月 08 11:51:49 KWDBServer1 kwbase[27530]: RPC client flags:    /usr/local/kaiwudb/bin/kwbase <client cmd> --host=192.1>
4月 08 11:51:49 KWDBServer1 kwbase[27530]: logs:                /var/lib/kaiwudb/logs
4月 08 11:51:49 KWDBServer1 kwbase[27530]: temp dir:            /var/lib/kaiwudb/kwbase-temp292448756
4月 08 11:51:49 KWDBServer1 kwbase[27530]: external I/O path:   /var/lib/kaiwudb/extern
4月 08 11:51:49 KWDBServer1 kwbase[27530]: store[0]:            path=/var/lib/kaiwudb
4月 08 11:51:49 KWDBServer1 kwbase[27530]: storage engine:      rocksdb
4月 08 11:51:49 KWDBServer1 kwbase[27530]: status:              initialized new cluster
4月 08 11:51:49 KWDBServer1 kwbase[27530]: clusterID:           4d7f4302-cdd9-4e04-a49e-08b8f0c4bf6b
4月 08 11:51:49 KWDBServer1 kwbase[27530]: nodeID:              1
lines 1-19/19 (END)

3.10、配置 KaiwuDB 开机自启动

说明：配置 KaiwuDB 开机自启动后，如果系统重启，则自动启动 KaiwuDB。

[root@KWDBServer1 kwdb_install]# systemctl enable kaiwudb
Created symlink /etc/systemd/system/multi-user.target.wants/kaiwudb.service → /etc/systemd/system/kaiwudb.service.

3.11、创建数据库管理用户

说明：执行add_user.sh创建数据库管理用户。

[root@KWDBServer1 kwdb_install]# ./add_user.sh
Please enter the username:kaiwudb
Please enter the password:

[ADD USER COMPLETED]:User creation completed.
[root@KWDBServer1 kwdb_install]#

四、使用KaiwuDB

4.1、使用命令行登录

[root@KWDBServer1 ~]# /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=192.168.40.201
#
# 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: 4d7f4302-cdd9-4e04-a49e-08b8f0c4bf6b
#
# Enter \? for a brief introduction.
#
root@192.168.40.201:26257/defaultdb> \?
You are using 'kwbase sql', KwDB's lightweight SQL client.
Type:
  \? or "help"      print this help.
  \q, quit, exit    exit the shell (Ctrl+C/Ctrl+D also supported).
  \! CMD            run an external command and print its results on standard output.
  \| CMD            run an external command and run its output as SQL statements.
  \set [NAME]       set a client-side flag or (without argument) print the current settings.
  \unset NAME       unset a flag.
  \show             during a multi-line statement or transaction, show the SQL entered so far.
  \h [NAME]         help on syntax of SQL commands.
  \hf [NAME]        help on SQL built-in functions.
  \l                list all databases in the KwDB cluster.
  \dt               show the tables of the current schema in the current database.
  \du               list the users for all databases.
  \d [TABLE]        show details about columns in the specified table, or alias for '\dt' if no table is specified.

root@192.168.40.201:26257/defaultdb> \dt
  table_name | table_type
-------------+-------------
(0 rows)

Time: 1.860406ms

root@192.168.40.201:26257/defaultdb>

4.2、使用KaiwuDB开发者中心连接

说明：

• 主机：192.168.40.201
• 数据库：defaultdb
• 用户名：kaiwudb
• 密码:自己设置的密码

五、常见问题

5.1、错误代码：ERROR: password authentication failed for user kaiwu

解决方案：创建数据库管理用户

[root@KWDBServer1 kwdb_install]# ./add_user.sh
Please enter the username:kaiwu
Please enter the password:

[ADD USER COMPLETED]:User creation completed.
[root@KWDBServer1 kwdb_install]#

六、总结

单点裸机部署步骤

• 登录待部署节点，编辑安装包目录下的deploy.cfg配置文件，设置安全模式、管理用户、服务端口等信息。默认情况下，deploy.cfg配置文件中包含集群配置参数，需删除或注释[cluster]集群配置项。
• 为deploy.sh脚本添加运行权限：chmod +x./deploy.sh。
• 执行单机部署安装命令：./deploy.sh install --single。执行成功后，控制台输出INSTALL COMPLETED: KaiwuDB has been installed successfuly!。
• 启动KaiwuDB节点：./deploy.sh start。执行成功后，控制台输出START COMPLETED: KaiwuDB has started successfuly!
• 查看KaiwuDB节点状态：./deploy.sh status或者systemctl status kaiwudb。
• 配置KaiwuDB开机自启动：systemctl enable kaiwudb。