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

前言

---

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

---

一、KWDB介绍

1.1 KWDB简介

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

1.2 主要特点

1. 高性能处理能力：支持海量时序数据高速读写，提供插值查询、数学函数等丰富的时序特色功能，提升应用效率。
2. 低运管成本：统一存储与管理多模数据，一套系统满足跨业务、跨部门数据融合需求，降低企业IT与运维投入。
3. 低存储成本：支持 5-30 倍数据压缩比，结合数据生命周期管理策略，灵活控制数据保留时间，显著节省存储资源。
4. 高安全性：提供数据库审计与加密机制，保障数据在复杂业务场景下的安全稳定运行。
5. 易用性强：提供标准 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	27.1.1	KWDB数据库

2.3 部署模式

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

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

三、下载容器镜像

执行以下命令，拉取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

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

4.1 创建部署目录

• 创建kwdb数据库目录

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

4.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

4.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

4.4 访问本地KWDB数据库

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

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

4.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

五、安全部署模式

5.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

5.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

5.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

5.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

5.5 访问KWDB数据库

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

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

5.5 创建用户和密码

• 创建用户 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

5.6 使用新用户连接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

6.1 安装环境要求

支持的操作系统

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

硬件环境

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

软件环境

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

6.2 安装 KaiwuDB 开发者中心

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

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

6.3 连接 KWDB 数据库

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

连接设置：

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

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

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

七、KWDB数据库的体验总结

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

---