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

搜索

免费试用

加载中~

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

KaiwuDB 社区官方号 time

2026-04-03

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

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

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

环境准备

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 ｕｐｄａｔｅ && 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 场景）

两种安装部署方式

方式一：二进制包一键部署

（推荐，单机/集群通用）

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+），未安装可以参考官方文档中有关安装教程：https://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

启动与验证（核心步骤）

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 ｅｘｅｃ -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. 插入测试数据
ｉｎｓｅｒｔ 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. 查询数据
ｓｅｌｅｃｔ * FROM device_metrics WHERE device_id = 'device_001';

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

常见问题与解决方案

问题现象	排查方向	解决方案
服务启动失败，日志显示端口占用	端口 26257/8080 被占用	`执行 sudo lsof-i :26257` 终止占用进程
集群模式安装失败	SSH 连接失败	检查脚本执行环境与集群环境 SSH 连接状态，是否已配置免密
依赖缺失导致安装失败	依赖未安装	参考「环境准备」重新安装对应依赖
Docker 启动报错	命令参数错误或其他错误	使用`docker logs kaiwudb-container` 输出容器日志进行排查
权限问题	当前用户无 sudo 权限	将当前用户添加至 sudo 组或使用其他有 sudo 权限的用户安装

总结

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

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

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

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

场景	推荐方式	适用人群
快速体验	Docker 部署	测试、学习、技术尝鲜
单机生产	二进制包	中小规模生产环境
高可用集群	3+ 节点部署	关键业务、连续性要求高