【KWDB 创作者计划】Docker单机环境下KWDB集群快速搭建指南

前言

---

KWDB是一款高性能、强一致的分布式数据库，具备高可用、易扩展、安全可靠等特性，适用于金融、物联网、实时大数据分析等多种场景。本文档旨在指导用户在Docker单机环境下快速搭建KWDB集群，体验其核心功能与部署流程。通过本指南，用户将掌握安全部署模式下的集群搭建、数据访问与同步测试等关键操作，为后续深入使用打下坚实基础。本实践面向技术爱好者和开发者，帮助其快速上手国产自研数据库的前沿代表——KWDB。

---

一、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	KaiwuDB集群	安全模式部署

2.3 本次部署介绍

本次实践将在Docker环境中以安全模式快速部署KaiwuDB单机集群，用于体验KWDB数据库的基本功能。整个过程操作简便，适合快速上手。

三、下载容器镜像

执行以下命令，拉取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 创建部署目录

在我们需要先提前创建好部署目录，这里直接创建/data/kwdb目录

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

4.2 创建证书文件

如需以安全模式部署KWDB集群，需使用命令创建CA证书、root用户客户端证书及节点服务器证书。若为跨节点部署，还需为每个节点生成并分发证书和密钥，并将root用户证书复制到需要访问集群的其他节点。

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'

4.3 查看证书相关文件

• 查看证书目录/data/kwdb/certs，可以看到已经生成相关证书文件，包括CA证书、root用户客户端证书及节点服务器证书等。

root@jeven01:/data/kwdb#  ll certs/
total 32
drwxr-xr-x 2 root root 4096 May  3 13:35 ./
drwxr-xr-x 3 root root 4096 May  3 13:28 ../
-rw-r--r-- 1 root root 1123 May  3 13:35 ca.crt
-rw------- 1 root root 1679 May  3 13:35 ca.key
-rw-r--r-- 1 root root 1127 May  3 13:35 client.root.crt
-rw------- 1 root root 1679 May  3 13:35 client.root.key
-rw-r--r-- 1 root root 1192 May  3 13:35 node.crt
-rw------- 1 root root 1679 May  3 13:35 node.key

五、安全部署模式

5.1 创建KWDB数据库实例1

我们以安全模式部署KWDB集群，创建KWDB数据库实例1，注意将本机的192.168.3.88替换为自己服务器的本地IP地址。

docker run -d --name kwdb1 --privileged \--ulimit memlock=-1 --ulimit nofile=1048576 \-p 26257:26257 -p 8080:8080 \-v /data/kwdb/certs:/kaiwudb/certs \-v /data/kwdb/kaiwudb1:/kaiwudb/deploy/kaiwudb-container \--ipc shareable -w /kaiwudb/bin \kwdb/kwdb:2.2.0 \./kwbase start --certs-dir=/kaiwudb/certs --listen-addr=0.0.0.0:26257 \--advertise-addr=192.168.3.88:26257 --http-addr=0.0.0.0:8080 \--store=/kaiwudb/deploy/kaiwudb-container --join 192.168.3.88:26257

• 主要参数解释：

参数	说明
--privileged	赋予容器扩展权限，提升容器内操作的灵活性和控制能力。
--ulimit memlock=-1	取消内存锁定限制，避免因内存不足导致数据库异常。
--ulimit nofile=1048576	设置容器内进程可打开的最大文件数为 1048576，满足高并发场景需求。
-p 26257:26257	映射数据库服务端口（宿主机端口:容器端口），用于客户端连接访问。
-p 8080:8080	映射 HTTP 管理界面端口（宿主机端口:容器端口），用于通过浏览器访问监控页面。
-v /data/kwdb/certs:/kaiwudb/certs	挂载证书目录，用于安全模式下存放 CA 证书、节点证书及密钥。
-v /data/kwdb/kaiwudb1:/kaiwudb/deploy/kaiwudb-container	数据持久化挂载点，确保容器重启后数据不丢失。
--ipc shareable	启用共享 IPC 命名空间，允许其他容器与其进行进程间通信。
-w /kaiwudb/bin	设置容器内工作目录为 /kaiwudb/bin，启动命令在此目录下执行。
kwdb/kwdb:2.2.0	使用的 Docker 镜像名称及标签，表示具体的镜像版本。
./kwbase start ...	容器启动时执行的数据库初始化与运行命令，包含集群配置参数。
--certs-dir=/kaiwudb/certs	指定证书存储目录（仅适用于安全模式）。
--listen-addr=0.0.0.0:26257	监听所有网络接口的指定端口，接受来自外部的数据库连接请求。
--advertise-addr=192.168.3.88:26257	指定该节点在集群中对外公布的地址和端口，供其他节点通信使用。
--http-addr=0.0.0.0:8080	指定 HTTP 接口监听地址和端口，用于访问 Web 控制台。
--store=/kaiwudb/deploy/kaiwudb-container	设置数据库数据文件的存储路径。
--join 192.168.3.88:26257	加入现有集群时使用的节点地址，可指定一个或多个初始节点。

5.2 创建KWDB数据库实例2

我们以安全模式部署KWDB集群，创建KWDB数据库实例2，注意将本机的192.168.3.88替换为自己服务器的本地IP地址。

docker run -d --name kwdb2 --privileged \--ulimit memlock=-1 --ulimit nofile=1048576 \-p 26258:26257 -p 8081:8080 \-v /data/kwdb/certs:/kaiwudb/certs \-v /data/kwdb/kaiwudb2:/kaiwudb/deploy/kaiwudb-container \--ipc shareable -w /kaiwudb/bin \kwdb/kwdb:2.2.0 \./kwbase start --certs-dir=/kaiwudb/certs --listen-addr=0.0.0.0:26257 \--advertise-addr=192.168.3.88:26258 --http-addr=0.0.0.0:8080 \--store=/kaiwudb/deploy/kaiwudb-container --join 192.168.3.88:26257

5.3 创建KWDB数据库实例3

我们以安全模式部署KWDB集群，创建KWDB数据库实例3，注意将本机的192.168.3.88替换为自己服务器的本地IP地址。

docker run -d --name kwdb3 --privileged \--ulimit memlock=-1 --ulimit nofile=1048576 \-p 26259:26257 -p 8082:8080 \-v /data/kwdb/certs:/kaiwudb/certs \-v /data/kwdb/kaiwudb3:/kaiwudb/deploy/kaiwudb-container \--ipc shareable -w /kaiwudb/bin \kwdb/kwdb:2.2.0  \./kwbase start --certs-dir=/kaiwudb/certs --listen-addr=0.0.0.0:26257 \--advertise-addr=192.168.3.88:26259 --http-addr=0.0.0.0:8080 \--store=/kaiwudb/deploy/kaiwudb-container --join 192.168.3.88:26257

5.4 检查各容器实例状态

检查各KWDB容器状态，确保容器正常运行。

root@jeven01:/data/kwdb# docker ps
CONTAINER ID   IMAGE             COMMAND                  CREATED              STATUS              PORTS                                       NAMES
01f1dc5471bc   kwdb/kwdb:2.2.0   "./kwbase start --ce…"   56 seconds ago       Up 55 seconds       0.0.0.0:8082->8080/tcp, :::8082->8080/tcp, 0.0.0.0:26259->26257/tcp, :::26259->26257/tcp   kwdb3
2581b7166274   kwdb/kwdb:2.2.0   "./kwbase start --ce…"   About a minute ago   Up About a minute   0.0.0.0:8081->8080/tcp, :::8081->8080/tcp, 0.0.0.0:26258->26257/tcp, :::26258->26257/tcp   kwdb2
e9b13a92fd0b   kwdb/kwdb:2.2.0   "./kwbase start --ce…"   2 minutes ago        Up 2 minutes        0.0.0.0:8080->8080/tcp, :::8080->8080/tcp, 0.0.0.0:26257->26257/tcp, :::26257->26257/tcp   kwdb1

5.5 初始化集群

执行以下命令，初始化KWDB集群。

docker exec kwdb1 ./kwbase init --certs-dir=/kaiwudb/certs --host=192.168.3.88:26257

六、访问KWDB集群

6.1 访问KWDB集群

使用 kwbase CLI 工具连接 KaiwuDB，如下所示：

docker exec -it kwdb1 ./kwbase sql --certs-dir=/kaiwudb/certs  --host=192.168.3.88:26257

6.2 查询数据库版本

我们查询当前安装的KWDB数据库版本，可以看到当前安装的版本为2.2.0版本。

SELECT version();

6.3 查询集群状态

退出KWDB集群，执行以下命令，查询当前KWDB集群状态。

root@jeven01:/data/kwdb# docker exec -it kwdb1 ./kwbase  node status --certs-dir=/kaiwudb/certsid |      address       |    sql_address     | build |            started_at            |            updated_at            |   locality   | start_mode | is_available | is_live
-----+--------------------+--------------------+-------+----------------------------------+----------------------------------+--------------+------------+--------------+----------1 | 192.168.3.88:26257 | 192.168.3.88:26257 | 2.2.0 | 2025-05-03 13:50:13.477659+00:00 | 2025-05-03 13:59:49.518005+00:00 | region=NODE1 | start  | true         | true2 | 192.168.3.88:26258 | 192.168.3.88:26258 | 2.2.0 | 2025-05-03 13:50:13.742053+00:00 | 2025-05-03 13:59:49.767398+00:00 | region=NODE2 | start  | true         | true3 | 192.168.3.88:26259 | 192.168.3.88:26259 | 2.2.0 | 2025-05-03 13:50:14.102759+00:00 | 2025-05-03 13:59:50.12104+00:00  | region=NODE3 | start  | true         | true
(3 rows)

七、测试数据同步

7.1 创建用户和密码

我们再次进入KWDB集群内，执行以下命令：

docker exec -it kwdb1 ./kwbase sql --certs-dir=/kaiwudb/certs  --host=192.168.3.88:26257

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

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

7.2 查询实例1的用户

在KWDB实例1中，我们查询新建jeven用户。

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

7.3 在实例2与实例3中查询用户

退出当前的 KWDB 数据库会话，连接到KWDB实例2中，可以看到用户jeven已经成功同步创建。

root@jeven01:/data/kwdb# docker exec -it kwdb2 ./kwbase sql --certs-dir=/kaiwudb/certs  --host=192.168.3.88:26257
#
# Welcome to the KWDB SQL shell.
# All statements must be terminated by a semicolon.
# To exit, type: \q.
#
# Server version: KaiwuDB 2.2.0 (x86_64-linux-gnu, built 2025/03/31 07:20:02, go1.16.15, gcc 11.4.0) (same version as client)
# Cluster ID: f8c4840f-e0b9-44bc-a16e-fab1877b1daa
#
# Enter \? for a brief introduction.
#
root@192.168.3.88:26257/defaultdb> show users;username |  options   | member_of
-----------+------------+------------admin    | CREATEROLE | {}jeven    |            | {admin}root     | CREATEROLE | {admin}
(3 rows)Time: 5.067895ms

退出当前的 KWDB数据库会话，连接到KWDB实例3中，可以看到用户jeven已经成功同步创建。

 docker exec -it kwdb3 ./kwbase sql --certs-dir=/kaiwudb/certs  --host=192.168.3.88:26257

show users;

八、实践总结

本次基于Docker的KWDB安全部署实践顺利完成，成功搭建了多节点集群并完成了数据访问与同步测试，验证了KWDB强大的分布式能力与稳定性。整个部署过程逻辑清晰、操作高效，体现出KWDB良好的文档支持和易用性。通过直观的命令行工具和可视化监控界面，进一步展示了其在集群管理与运维方面的优势。作为一款优秀的国产自研数据库，KWDB在性能、功能与安全性方面表现突出，具备广阔的应用前景，值得深入研究与推广使用。

---