本文内容基于 KWDB 3.1.0 版本实践编写。KaiwuDB（KWDB）是 KaiwuDB 的开源社区版，面向开发者免费开放，支持分布式部署、时序存储引擎和标准 SQL。
如果你在部署或使用中遇到问题，或者想下载最新版本，可访问 KaiwuDB 官网获取完整文档和社区支持。

文章目录

本文面向需要快速体验或部署开源分布式数据库的开发者和运维人员，解决 KWDB 安装过程中常见的系统依赖、安装包选择、Docker 启动、集群初始化和连接验证问题。文章以当前稳定版本 KWDB V3.1.0 为示例，介绍二进制安装包部署和 Docker 容器部署两种方式，并覆盖单机、单副本集群和多副本集群场景。完成本文步骤后，读者可以启动 KWDB 服务，使用 kwbase CLI 连接数据库，并通过基础 SQL 验证部署结果。

01 环境准备

1.1 硬件要求

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+）。

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 常见问题与解决方案

05 总结

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

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

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

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

常见问题 FAQ

Q1：KWDB 支持哪些部署方式？

本文介绍二进制安装包和 Docker 容器两种方式。二进制方式适合单机及多节点集群部署，Docker 方式更适合快速体验、开发和测试。

Q2：如何选择 KWDB 的安装版本？

优先使用 KWDB Gitee 发布页中的稳定版本，并根据 CPU 架构和操作系统选择对应安装包。

Q3：KWDB 部署后如何验证服务是否正常？

可以先使用 systemctl status 或 docker ps 查看服务状态，再使用 kwbase sql 连接数据库，执行建库、建表、插入和查询操作。验证命令中的容器名称必须与 docker run --name 或 Compose 配置保持一致。

Q4：KWDB 集群部署前需要准备什么？

需要提前确认节点之间网络互通、端口未被占用、操作系统和 CPU 架构一致，并配置部署节点到其他节点的 SSH 免密登录。多副本集群还需要根据副本数规划节点数量、数据目录和安全策略。

KWDB 提供二进制安装包和容器部署方式，适用于从本地体验、开发测试到多节点集群部署的不同场景。单机或 Docker 方式适合快速验证功能；生产环境部署则需要进一步配置安全模式、数据目录、节点通信、SSH 免密和副本策略。

如果在 KWDB 安装过程中遇到依赖缺失、端口冲突、容器启动失败或集群初始化问题，欢迎在评论区提出操作系统、KWDB 版本和错误信息。

相关推荐：

KWDB 3.2.1 版本发布，数据类型与时区设置体验优化

【KaiwuDB 运维篇】高可用：从单点到多副本的进化

KWDB 快速部署文档

更新日期：2026-08-12

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

基于STM32的全屋环境智能监测与预警终端设计

avatar 亚马逊云科技技术品牌专区

Keras：面向人类的深度学习库

Keras3支持多后端（TensorFlow、PyTorch、JAX），通过设置环境变量切换，兼容指定版本。pip安装后可用Sequential API快速构建CNN模型，如MNIST分类示例，实

avatar 亚马逊云科技技术品牌专区

AI行业日报｜2026-09-25：5个热点事件

本期行业动态聚焦于端侧算力重构、自主智能体工作流、开发工具经济模型、网络隔离架构设计与公共部门合规审查。以下结合一线技术场景进行结构化梳理，供 AI 研究员与软件工程团队参考。 PrismML 正将其轻量级语言模型适配至搭载高通处理器的智能眼镜终端 1 。该平台的核心战略指向开源权重模型的本地化运行，旨在最大化挖掘穿戴设备现有算力的利用效率 1 。对于嵌入式与边缘计算开发者而言，此类微型模型向低功

avatar 亚马逊云科技技术品牌专区