【KWDB 创作者计划】使用Docker实现KWDB数据库的快速部署与配置

前言
一、KWDB介绍
- 1.1 KWDB简介
- 1.2 主要特点
- 1.3 典型应用场景
二、环境介绍
- 2.1 部署环境要求
- 2.2 本地环境规划
- 2.3 部署模式
三、部署Docker环境
- 3.1 安装相关工具
- 3.2 配置Docker软件源
- 3.3 更新软件源
- 3.4 安装Docker
- 3..5 配置镜像加速
- 3.6 检查Docker版本
四、下载容器镜像
五、非安全部署模式（可选）
- 5.1 创建部署目录
- 5.2 创建KWDB容器
- 5.3 检查容器状态
- 5.4 访问本地KWDB数据库
- 5.5 使用普通用户访问KWDB
六、安全部署模式
- 6.1 创建证书文件
- 6.2 创建KWDB容器
- 6.3 查看容器状态
- 6.4 查看容器日志
- 6.5 访问KWDB数据库
- 6.6 创建用户和密码
- 6.7 使用新用户连接KWDB
七、使用KaiwuDB开发者中心连接KWDB
- 7.1 安装环境要求
- 7.2 安装 KaiwuDB 开发者中心
- 7.3 连接 KWDB 数据库
八、KWDB数据库体验与总结

前言

随着 AIoT 技术的快速发展，对数据库的多模数据处理能力和智能化水平提出了更高要求。KaiwuDB 作为一款面向 AIoT 场景的国产分布式数据库，凭借其高效的时序数据处理能力与多模融合特性，逐渐成为行业关注的焦点。本文将通过 Docker 容器化方式，带大家快速部署并体验 KaiwuDB 数据库的强大功能与便捷管理。

一、KWDB介绍

1.1 KWDB简介

KWDB 是一款面向 AIoT 场景的分布式、多模融合数据库产品。支持在同一个实例中建立时序库和关系库，并统一处理多种类型的数据，具备对海量时序数据的高效读写与分析能力。产品具备高可用、安全稳定、易运维等特性，广泛应用于工业物联网、数字能源、车联网、智慧矿山等多个行业领域，为用户提供一站式数据存储、管理与分析的基础平台。

在这里插入图片描述

1.2 主要特点

高性能处理能力：支持海量时序数据高速读写，提供插值查询、数学函数等丰富的时序特色功能，提升应用效率。
低运管成本：统一存储与管理多模数据，一套系统满足跨业务、跨部门数据融合需求，降低企业IT与运维投入。
低存储成本：支持 5-30 倍数据压缩比，结合数据生命周期管理策略，灵活控制数据保留时间，显著节省存储资源。
高安全性：提供数据库审计与加密机制，保障数据在复杂业务场景下的安全稳定运行。
易用性强：提供标准 SQL 接口、高速写入、极速查询、集群部署等能力，与第三方工具无缝集成，开发运维更便捷。

1.3 典型应用场景

应用场景	场景描述
工业物联网	支持 SCADA/DCS 系统对接，统一存储设备实时数据与生产管理数据，助力智能化生产分析。
数字能源	融合传感器与业务数据，实现调峰调频分析与实时预警，推动能源系统智能化升级。
车联网	高速写入车端传感器数据，支撑车辆状态监控与上层业务分析，打造智能车联网解决方案。
智慧矿山	统一处理采选冶全流程中的关系与时序数据，打通多业务系统，提升矿山数字化水平。

二、环境介绍

2.1 部署环境要求

KWDB数据库的硬件规格要求

项目	要求
`CPU 和内存`	单节点建议配置不低于 4 核心 CPU 和 8 GB 内存。对于数据量大、复杂的工作负载、高并发以及对性能要求较高的场景，建议增加 CPU 核心数和内存容量，以确保系统的高效运行和稳定性。
`磁盘`	- 推荐使用 SSD 或 NVMe 存储设备，避免使用 NFS、CIFS、CEPH 等共享存储。 - 磁盘需具备至少 500 IOPS（每秒输入输出操作次数）和 30 MB/s 的处理效率，以满足数据库的读写需求。
`文件系统`	建议使用 ext4 文件系统，以提供良好的兼容性和性能表现。
`备注`	在实际部署过程中，用户应根据具体的业务规模和性能需求灵活规划硬件资源，确保系统能够高效稳定地运行。

KWDB 支持在以下已安装 Docker的操作系统中进行容器部署

操作系统	版本	架构
Anolis	7.9	ARM_64、x86_64
Anolis	8.6	ARM_64、x86_64
CentOS	7	x86_64
CentOS	8	x86_64
Debian	V11	ARM_64
KylinOS	V10 SP3 2403	ARM_64、x86_64
KylinOS	V10 SP3 2303	ARM_64、x86_64
openEuler	22.03	x86_64
Ubuntu	V18.04	x86_64
Ubuntu	V20.04	ARM_64、x86_64
Ubuntu	V22.04	ARM_64、x86_64
Ubuntu	V24.04	ARM_64、x86_64
UOS	1050e	x86_64
UOS	1060e	ARM_64、x86_64
UOS	1070e	x86_64

2.2 本地环境规划

本次实践为个人测试环境，操作系统版本为Ubuntu 22.04.1。

hostname	IP地址	操作系统版本	Docker版本	部署项目
jeven01	192.168.3.88	Ubuntu 22.04.1 LTS	28.1.1	KWDB数据库

2.3 部署模式

使用容器镜像部署KaiwuDB的部署模式说明：

部署方式	描述	支持的部署模式	备注
Docker Compose 和 YAML配置文件	基于Docker Compose及YAML配置文件进行部署，简化了多容器应用的管理和配置。	非安全部署模式	使用YAML文件部署KaiwuDB
docker run命令行	通过执行`docker run`命令直接启动容器，提供了更高的灵活性和控制力。	安全和非安全部署模式	执行Docker Run命令部署KaiwuDB

三、部署Docker环境

3.1 安装相关工具

安装docker之前，我们先安装 HTTPS传输工具及必要组件。

 apt  install -y apt-transport-https ca-certificates curl gnupg lsb-release software-properties-common

在这里插入图片描述

3.2 配置Docker软件源

添加阿里云 GPG 密钥

mkdir -p /etc/apt/keyrings
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker-archive-keyring.gpg

执行以下命令，开始配置阿里云 Docker 软件源。

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker-archive-keyring.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

3.3 更新软件源

使用apt-get update命令，更新软件源。

root@jeven01:~# apt update
Hit:1 https://mirrors.aliyun.com/ubuntu jammy InRelease
Hit:2 https://mirrors.aliyun.com/ubuntu jammy-security InRelease
Hit:3 https://mirrors.aliyun.com/ubuntu jammy-updates InRelease
Hit:4 https://mirrors.aliyun.com/ubuntu jammy-backports InRelease
Hit:5 https://mirrors.aliyun.com/docker-ce/linux/ubuntu jammy InRelease
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
194 packages can be upgraded. Run 'apt list --upgradable' to see them.

3.4 安装Docker

执行以下命令，安装Docker核心组件。

apt  install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

在这里插入图片描述

3…5 配置镜像加速

执行以下命令，快速配置Docker镜像加速。可以自行添加多个Docker镜像加速源，确保后续可以成功拉取Docker镜像。

mkdir -p /etc/docker

sudo  tee /etc/docker/daemon.json > /dev/null <<EOF
{"registry-mirrors": ["https://80c84f5330e14908928ca78944e61dc4.mirror.swr.myhuaweicloud.com"]
}
EOF

执行以下命令，配置Docker开机自启。

systemctl daemon-reload
systemctl restart docker

3.6 检查Docker版本

检查Docker版本，可以看到当前安装的版本为28.1.1。

root@jeven01:~# docker -v
Docker version 28.1.1, build 4eba377

检查Docker compose版本，当前安装版本为2.35.1。

root@jeven01:~# docker compose version
Docker Compose version v2.35.1

四、下载容器镜像

执行以下命令，拉取KWDB容器镜像。本次实践所使用的KWDB镜像为kwdb/kwdb:2.2.0。

root@jeven01:/data/kwdb# docker pull kwdb/kwdb:2.2.0
2.2.0: Pulling from kwdb/kwdb
Digest: sha256:9dda946922a69557e20be9f1d99c504c467fba6351bb8af0a34fe42711cde73f
Status: Image is up to date for kwdb/kwdb:2.2.0
docker.io/kwdb/kwdb:2.2.0

在这里插入图片描述

五、非安全部署模式（可选）

5.1 创建部署目录

mkdir -p /data/kwdb   &&  cd /data/kwdb/

5.2 创建KWDB容器

使用docker run命令方式部署，可参考以下：

docker run -d --privileged --name kaiwudb \--ulimit memlock=-1 \--ulimit nofile=65535 \-p 26257:26257 \-p 8080:8080 \-v /var/lib/kaiwudb:/kaiwudb/deploy/kaiwudb-container \--ipc shareable \-w /kaiwudb/bin \kwdb/kwdb:2.2.0 \./kwbase start-single-node \--insecure \--listen-addr=0.0.0.0:26257 \--http-addr=0.0.0.0:8080 \--store=/kaiwudb/deploy/kaiwudb-container

使用 Docker Compose和YAML配置文件部署，目前只支持非安全部署模式，

version: '3.3'
services:kaiwudb-container:image: "kwdb/kwdb:2.2.0"container_name: kaiwudb-experiencehostname: kaiwudb-experienceports:- 8080:8080- 26257:26257ulimits:memlock: -1volumes:- /dev:/devnetworks:- defaultrestart: on-failureipc: shareableprivileged: trueenvironment:- LD_LIBRARY_PATH=/kaiwudb/libtty: trueworking_dir: /kaiwudb/bincommand:- /bin/bash- -c- |/kaiwudb/bin/kwbase start-single-node --insecure --listen-addr=0.0.0.0:26257 --advertise-addr=127.0.0.1:26257 --http-addr=0.0.0.0:8080 --store=/kaiwudb/deploy/kaiwudb

部署文件相关参数解释

参数/选项	描述
`image: "kwdb/kwdb:2.2.0"`	指定使用的容器镜像及其标签，这里是 kwdb/kwdb:2.2.0。
`container_name: kaiwudb-experience`	容器的名称。
`hostname: kaiwudb-experience`	容器的主机名。
`ports:`	端口映射列表，将宿主机端口映射到容器内部端口。
`- 8080:8080`	将宿主机的 8080 端口映射到容器内的 8080 端口（HTTP 服务）。
`- 26257:26257`	将宿主机的 26257 端口映射到容器内的 26257 端口（数据库主端口）。
`ulimits:`	设置容器的资源限制。
`memlock: -1`	取消内存锁定限制。
`volumes:`	定义卷挂载，用于数据持久化或共享配置文件等。
`- /dev:/dev`	将宿主机的 `/dev` 目录挂载到容器内相同位置。
`networks:`	定义网络设置，默认使用 `default` 网络。
`restart: on-failure`	当容器由于错误退出时自动重启。
`ipc: shareable`	允许其他容器共享此容器的IPC命名空间。
`privileged: true`	赋予容器扩展权限。
`environment:`	设置环境变量。
`- LD_LIBRARY_PATH=/kaiwudb/lib`	设置库路径环境变量。
`tty: true`	分配一个伪TTY，保持容器运行。
`working_dir: /kaiwudb/bin`	设置容器内的工作目录。
`command:`	覆盖默认的容器启动命令。
`- /bin/bash -c "/kaiwudb/bin/kwbase start-single-node --insecure ..."`	启动 KaiwuDB 的具体命令及参数（非安全模式）。

启动命令参数说明：

参数	描述
`--insecure`	（仅非安全模式）指定以非安全模式运行。
`--listen-addr=0.0.0.0:26257`	指定数据库监听的地址和端口。
`--advertise-addr=127.0.0.1:26257`	指定对外广播的地址和端口。
`--http-addr=0.0.0.0:8080`	指定 HTTP 接口监听的地址和端口。
`--store=/kaiwudb/deploy/kaiwudb`	指定数据存储位置。

执行docker compose up -d 命令，运行KWDB容器

root@jeven01:/data/kwdb# docker compose up -d
[+] Running 2/2✔ Network kwdb_default          Created                                                                                                          0.1s✔ Container kaiwudb-experience  Started                                                                                                          0.2s

在这里插入图片描述

5.3 检查容器状态

检查KWDB容器状态，确保容器正常启动。

root@jeven01:/data/kwdb# docker compose ps
NAME                 IMAGE               COMMAND                  SERVICE             CREATED             STATUS              PORTS
kaiwudb-experience   kwdb/kwdb:2.2.0     "/bin/bash -c '/kaiw…"   kaiwudb-container   5 minutes ago       Up 5 minutes        0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 0.0.0.0:26257->26257/tcp, :::26257->26257/tcp

5.4 访问本地KWDB数据库

我们使用 KaiwuDB 提供的内置命令行工具 kwbase 连接数据库。该工具支持以安全模式（适用于生产环境）或非安全模式（适用于测试环境）进行连接，便于用户执行数据库操作与维护。在非安全模式部署时，KaiwuDB 允许任意用户无需密码即可连接，通常用于本地开发和测试场景。

docker exec -it kaiwudb-experience ./kwbase sql --insecure  --host=127.0.0.1

在这里插入图片描述

5.5 使用普通用户访问KWDB

进入KWDB数据库后，我们创建新用户zhangsan，如下所示：

CREATE USER zhangsan;

执行以下命令，查询刚新建的zhangsan用户。

show users;

在这里插入图片描述

我们使用刚创建的zhangsan普通用户，在非安全模式下免密登录KWDB数据库。

docker exec -it kaiwudb-experience ./kwbase sql --insecure  --host=127.0.0.1 -u zhangsan

在这里插入图片描述

六、安全部署模式

6.1 创建证书文件

在以 TLS 安全模式部署 KaiwuDB 时，需先通过一系列命令创建数据库的证书颁发机构（CA）、root 用户的客户端证书以及节点服务器证书。这些证书为系统提供身份验证和加密通信能力，是实现安全部署的基础步骤。创建节点证书时，请确保将本地IP地址（例如192.168.3.88）包含在内，以生成正确的服务器证书。

docker run --rm --privileged \-v /data/kwdb/certs:/kaiwudb/certs \-w /kaiwudb/bin \kwdb/kwdb:2.2.0  \bash -c './kwbase cert create-ca --certs-dir=/kaiwudb/certs --ca-key=/kaiwudb/certs/ca.key && \./kwbase cert create-client root --certs-dir=/kaiwudb/certs --ca-key=/kaiwudb/certs/ca.key && \./kwbase cert create-node 127.0.0.1 localhost 0.0.0.0  192.168.3.88 --certs-dir=/kaiwudb/certs --ca-key=/kaiwudb/certs/ca.key'

在这里插入图片描述

查看在certs目录下的证书相关文件，如下所示：

root@jeven01:/data/kwdb# ls certs/
ca.crt  ca.key  client.root.crt  client.root.key  node.crt  node.key

6.2 创建KWDB容器

以TLS安全模式，创建KWDB容器，如下所示：

docker run -d --privileged --name kwdb \
--ulimit memlock=-1 \
--ulimit nofile=65535 \
-p 26257:26257 \
-p 8080:8080 \
-v /data/kwdb/certs:/kaiwudb/certs \
-v /data/kwdb/db:/kaiwudb/deploy/kaiwudb-container \
--ipc shareable \
-w /kaiwudb/bin \kwdb/kwdb:2.2.0  \
./kwbase start-single-node \--certs-dir=/kaiwudb/certs \--listen-addr=0.0.0.0:26257 \--http-addr=0.0.0.0:8080 \--store=/kaiwudb/deploy/kaiwudb-container

在这里插入图片描述

6.3 查看容器状态

我们查询KWDB容器状态，确保KWDB容器创建成功。

root@jeven01:/data/kwdb# docker ps
CONTAINER ID   IMAGE             COMMAND                  CREATED          STATUS          PORTS                               NAMES
3fd88edd6fce   kwdb/kwdb:2.2.0   "./kwbase start-sing…"   53 seconds ago   Up 52 seconds   0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 0.0.0.0:26257->26257/tcp, :::26257->26257/tcp   kwdb

6.4 查看容器日志

查询KWDB容器日志，确保KWDB数据库正常运行。

root@jeven01:/data/kwdb# docker logs kwdb
KWDB node starting at 2025-05-02 12:48:38.138252587 +0000 UTC (took 0.6s)
build:                2.2.0 @ 2025/03/31 07:20:02 (go1.16.15)
sql:                 postgresql://root@0.0.0.0:26257?sslcert=%2Fkaiwudb%2Fcerts%2Fclient.root.crt&sslkey=%2Fkaiwudb%2Fcerts%2Fclient.root.key&sslmode=verify-full&sslrootcert=%2Fkaiwudb%2Fcerts%2Fca.crt
RPC client flags:    ./kwbase <client cmd> --host=0.0.0.0:26257 --certs-dir=/kaiwudb/certs
logs:                /kaiwudb/deploy/kaiwudb-container/logs
temp dir:            /kaiwudb/deploy/kaiwudb-container/kwbase-temp995376563
external I/O path:   /kaiwudb/deploy/kaiwudb-container/extern
store[0]:            path=/kaiwudb/deploy/kaiwudb-container
storage engine:      rocksdb
status:              restarted pre-existing node
clusterID:           99227f6f-9dca-4105-b498-1c243f0f703c
nodeID:              1

6.5 访问KWDB数据库

使用 kwbase CLI 工具连接 KaiwuDB 时，请确保以部署数据库时所创建的用户进行登录。这种方式保证了操作的安全性和权限管理的准确性。

docker exec -it kwdb ./kwbase sql --certs-dir=/kaiwudb/certs  --host=192.168.3.88

在这里插入图片描述

6.6 创建用户和密码

创建用户 jeven，设置密码为 jeven1234，并赋予管理员权限（角色为 admin）

CREATE USER jeven WITH PASSWORD 'jeven1234';
GRANT admin TO jeven;

在这里插入图片描述

查询新建jeven用户，如下所示：

方法一：

SELECT * FROM  system.users;

在这里插入图片描述

方法二：

root@192.168.3.88:26257/defaultdb> SHOW USERS;username |  options   | member_of
-----------+------------+------------admin    | CREATEROLE | {}jeven    |            | {admin}root     | CREATEROLE | {admin}
(3 rows)Time: 10.348748ms

6.7 使用新用户连接KWDB

退出当前的 KWDB 数据库会话，然后使用新生成的 jeven 用户重新连接 KWDB 数据库。

docker exec -it  kwdb ./kwbase sql --certs-dir=/kaiwudb/certs  --host=192.168.3.88    --host=192.168.3.88 -u jeven

在这里插入图片描述

七、使用KaiwuDB开发者中心连接KWDB

7.1 安装环境要求

支持的操作系统

Windows: Windows 7 及以上 64 位系统
Linux: 内核 2.6 及以上系统
macOS: Mac 操作系统

硬件环境

项目	要求
内存	1G 及以上
硬盘	10G 及以上

软件环境

项目	要求
KaiwuDB 版本	2.0 及以上版本
OpenJRE	8 及以上版本

7.2 安装 KaiwuDB 开发者中心

下载地址：https://gitee.com/kwdb/kwdb/releases/tag/V2.2.0

在这里插入图片描述

下载后解压软件包，直接双击KaiwuDB Developer Center.exe，即可运行 KaiwuDB 开发者中心应用程序。

在这里插入图片描述

7.3 连接 KWDB 数据库

在创建新连接窗口中，选择 KaiwuDB 驱动，然后单击下一步按钮以继续。

在这里插入图片描述

连接设置：

主机名称：192.168.3.88（本机IP），端口默认26257；
数据库：defaultdb；
用户：新创建的用户jeven;
密码：自己设置的密码；
确认连接：填写完毕后，点击“完成”确认即可。
备注：确认连接前，可单击测试链接，检查连接是否成功。

在这里插入图片描述

连接成功，进入KWDB数据库，如下所示：

在这里插入图片描述

我们在 SQL 编辑器中输入并执行用户的查询语句后，即可查看用户列表信息。

在这里插入图片描述

八、KWDB数据库体验与总结

通过本次实践，我深刻体会到 KWDB 数据库作为一款国产分布式数据库的强大能力与优秀设计。尽管是首次接触，但借助 Docker 的快速部署方式，整个安装配置过程简洁高效，即使是技术小白也能轻松上手。无论是非安全模式还是安全部署模式，KWDB 都提供了清晰的操作流程和良好的系统支持。其内置的多模数据处理能力和对 AI 能力的融合，让我看到了它在工业物联网、车联网等复杂场景中的巨大潜力。KWDB 不仅性能稳定、功能丰富，而且具备高度的可操作性和前瞻性，是一款值得深入学习与广泛应用的国产数据库产品。