简单几步搞定 KaiwuDB 社区版安装部署！看这一篇就够了

  • KaiwuDB

    2026-04-03 14:48:50
  • 国内数据库
  • 原创

拿到一款新数据库，最让人头疼的往往不是功能够不够强，而是第一步“装起来”就遇到各种问题——环境怎么配？单机体验和生产部署有什么区别？Docker 怎么跑？

别担心，这篇文章为你准备了一份  KaiwuDB 社区版全场景安装指南 。从环境准备，到三种模式（单机、集群、容器）的安装步骤，再到验证连接和常见问题排查，全都帮你梳理清楚了。无论你是快速体验尝鲜，还是为正式项目做准备，跟着这篇文章走，就能顺利跑通第一个 KaiwuDB 实例。

接下来，我们从环 境准 备开始，一步步拆解三种场景下的具体操作吧！

 



01  环境准备


1.1  硬件要求

 

维度

说明

CPU

支持 x86_64、arm64、loongarch64 等架构，核心数量不低于 4 核

内存

最低配置 8G

磁盘

1.推荐使用 SSD 或者 NVMe 设备，尽量避免使用 NFS、CIFS、CEPH 等共享存储 

2.磁盘必须能够实现 500 IOPS 和 30 MB/s 处理效率 

3.使用 HDD 硬盘部署单机版本时，避免设备数过多或每秒写入测点数过高，否则数据写入性能将显著下降 

4.KaiwuDB 系统自身启动不会占用过多磁盘容量（低于  1G）。实际所需磁盘大小主要取决于用户的业务量

文件系统

建议使用 ext4 文件系统


 


1.2 依赖安装

•  Ubuntu/Debian 系

 


# 并安装依赖




sudo
 apt update &&
 sudo
 apt install -y libgflags2.2 libprotoc32t64 libssl3t64 zlib1g liblz4-1 liblzma5 libkrb5-3 libncurses6

 

•  CentOS/RHEL 系

 


# 安装依赖




sudo
 yum install -y gflags openssl-libs lz4 zlib xz-libs protobuf krb5-libs ncurses-libs

 



1.3 安装包获取

下载地址 ：

•  KaiwuDB 官网下载中心

•  KaiwuDB 社区版发布仓库： https://gitee.com/kwdb/kwdb/releases

选择对应系统版本的安装包：

•  二进制包： KWDB-版本-系统版本-架构-debs/rpms/docker.tar.gz （ 推荐）

•  容器镜像： kwdb/kwdb:版本 （Docker 场景）


02  两种安装部署方式

方式一：二进制包一键部署
（推荐，单机/集群通用）


 

2.1 解压安装包

 


# 创建安装目录并解压




mkdir
 -p /soft &&
 cd
 /soft




# 替换为实际下载的包名



tar -xvf KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz




cd
 kwdb_install/

 

 

2.2 配置

 

修改  deploy.cfg  配置文件，自定义端口、存储路径等：

 


[global]



secure_mode=tls # 是否开启加密传输，可选择 tls/tlcp/insecure



management_user=kaiwudb # 创建的系统用户名称



rest_port=8080 # http 服务端口



kaiwudb_port=26257 # kwdb 服务端口



brpc_port=27257 # brpc 远程调用端口



data_root=/var/lib/kaiwudb # kwdb 数据存放路径



[local]



node_addr=127.0.0.1 # 本机IP



# 若部署集群模式需要进行以下配置，若安装单机版需删除以下配置



[cluster]



node_addr=127.0.0.2 # 集群其他节点IP，多个节点使用逗号分隔



ssh_port=22 # 集群其他节点 SSH 连接端口



ssh_user=songxing # 集群其他节点 SSH 连接用户

 

部署集群时除本机外的其他节点均使用 SSH 进行连接后进行部署，请为其他节点配置相同的 SSH 端口和用户以及本机到其他节点的 SSH 免密。


 

2.3 执行安装

 


# 单机安装



./deploy.sh install --single




# 单副本集群安装



./deploy.sh install --single-replica




# 三副本集群安装



./deploy.sh install --multi-replica

 

 

2.4 单机启动/集群初始化

 

 


# 单机模式安装后可以使用系统服务或脚本启动数据库



systemctl daemon-reload && systemctl start kaiwudb



./deploy.sh start




# 单副本及三副本集群安装完成后，需要执行初始化命令完成整个集群初始化



./deploy.sh cluster --init

 

•  后续数据库运维均可使用 systemd 对数据库服务进行管理

•  初始化集群执行完成后,会启动所有节点中的 KaiwuDB 数据库并完成整个集群初始化


方式二：Docker 容器部署
（快速体验/测试环境）


 

2.1 前提条件

已安装 Docker 及 Docker Compose（v2+），未安装可以参考官方文档中有关安装教程： h ttps://docs.docker.com/engine/install/ 。


 

2.2 快速启动（单节点非安全模式）

 


# 拉取镜像（3.1.0最新版）



docker pull kwdb/kwdb:3.1.0




# 启动容器



docker run -d \



  --name kaiwudb-container \



  -p 26257:26257 \



  -p 8080:8080 \



  -p 27257:27257 \



  -w /kaiwudb/bin \



  -v /data/kaiwudb:/kaiwudb/deploy/kaiwudb-container \



  kwdb/kwdb:3.1.0 \



  /kaiwudb/bin/kwbase start-single-node --insecure --listen-addr=0.0.0.0:26257 --http-addr=0.0.0.0:8080 --brpc-addr=0.0.0.0:27257 --store=/kaiwudb/deploy/kaiwudb-container

 

 


2.3 使用 Docker Compose 进行快速部署体验（单节点非安装模式快速启动）

 

创建  docker-compose.yml ：

 


services:



  kaiwudb:



    image:
 kwdb/kwdb:3.1.0



    container_name:
 kaiwudb-container



    working_dir:
 /kaiwudb/bin



    ports:




      -
 26257
:26257




      -
 8080
:8080




      -
 27257
:27257



    volumes:




      -
 /data/kaiwudb:/kaiwudb/deploy/kaiwudb-container



    restart:
 unless-stopped



    ulimits:



      memlock:
 -1



    environment:




      -
 TZ=Asia/Shanghai



    entrypoint:
 [
"/kaiwudb/bin/kwbase"
,
 "start-single-node"
,
 "--insecure"
,
 "--listen-addr=0.0.0.0:26257"
,
 "--http-addr=0.0.0.0:8080"
,
 "--brpc-addr=0.0.0.0:27257"
,
 "--store=/kaiwudb/deploy/kaiwudb-container"
]

 

启动：

 

docker compose up -d

 


03  启动与验证（核心步骤）


 

3.1 启动服务

 

• 二进制包/源码部署

 


# 启动服务




sudo
 systemctl start kaiwudb




# 设置开机自启




sudo
 systemctl
 enable
 kaiwudb

 

• Docker 部署

 


# 启动容器



docker start kaiwudb




# 查看容器状态



docker ps | grep kaiwudb

 

 


3.2 验证服务状态

 

 


# 查看服务状态（安装包方式）




sudo
 systemctl status kaiwudb




# 查看容器日志（Docker）



docker logs kaiwudb

 

•  正常状态： 输出 active (running)，日志无报错。


 

3.3 连接数据库

• 使用安装包部署

 


# 执行以下命令可快速进入 kwdb sql 命令行



kw-sql

 

• Docker 部署

 


# 进入容器并连接



docker
 exec
 -it kaiwudb /kaiwudb/bin/kwbase sql --insecure --host=127.0.0.1:26257

 

•  连接成功标识 ： 进入  kwbase>  命令行提示符，可执行 SQL 操作。


 

3.4 基础测试（验证功能）

 


-- 1. 创建测试数据库




CREATE
 DATABASE test_db;



USE test_db;







-- 2. 创建时序表（包含时间戳与设备ID，多模核心特性）




CREATE TABLE
 device_metrics (




  time
 TIMESTAMP
 NOT NULL
,



  device_id STRING
 NOT NULL
,



  temperature
 FLOAT
,



  humidity
 FLOAT
,




  PRIMARY KEY
 (
time
, device_id)



);







-- 3. 插入测试数据




INSERT INTO
 device_metrics
 VALUES



(
'2026-03-16 10:00:00'
,
 'device_001'
,
 25.3
,
 45.2
),



(
'2026-03-16 10:05:00'
,
 'device_001'
,
 25.5
,
 44.8
);







-- 4. 查询数据




SELECT
 *
 FROM
 device_metrics
 WHERE
 device_id
 =
 'device_001'
;

 

执行无报错，返回数据即部署成功。


04  常见问题与解决方案

问题现象

排查方向

解决方案

服务启动失败，日志显示端口占用

端口 26257/8080 被占用

执行 sudo lsof-i :26257   终止占用进程

集群模式安装失败

SSH 连接失败

检查脚本执行环境与集群环境 SSH 连接状态，是否已配置免密

依赖缺失导致安装失败

依赖未安装

参考「环境准备」重新安装对应依赖

Docker 启动报错

命令参数错误或其他错误

使用 docker logs kaiwudb-container  输 出容器日志进行排查

权限问题

当 前 用户无  sudo 权限

将当前用户添加至 sudo 组或使用其他有 sudo 权限的用户安装



05  总结

最后，简单为大家总结一下三种场景怎么选：

•  如果你想 快速上手体验 ，不用纠结，直接选 Docker 部署，一行命令就能跑起来，最适合拿来测试和学习。

•  如果你准备 单机上线生产 ，二进制包一键部署更稳妥，配置灵活，稳定性也更有保障。

•  如果你需要 搭建高可用集群 ，建议部署 3 个节点以上，再配上防火墙和安全策略，业务连续性才真正稳得住。

场景

推荐方式

适用人群

快速体验

Docker 部署

测试、学习、技术尝鲜

单机生产

二进制包

中小规模生产环境

高可用集群

3+ 节点部署

关键业务、连续性要求高


以上就是本期 KaiwuDB 社区版安装部署实战分享，如果你在实际操作中遇到什么问题，欢迎在评论区留言交流 。更多 KaiwuDB 技术干货，请持续关注我们的公众号，下 期 见 ！



请使用浏览器的分享功能分享到微信等