文档下载建议反馈入口

  • 部署准备
    • 硬件
    • 操作系统
    • 软件依赖（可选）
    • 端口要求
    • 安装包和可视化安装程序
  • 部署 KaiwuDB
    • 使用脚本部署 KaiwuDB
    • 使用可视化向导部署 KaiwuDB
    • 使用 YAML 文件部署 KaiwuDB
    • 执行 Docker Run 命令部署 KaiwuDB
  • 配置许可证

单节点容器部署

KaiwuDB 支持多种容器化部署方式，以满足不同用户的部署需求：

部署方式特点适用用户/场景技术要求详细指南
脚本部署（推荐）使用安装包内置脚本，一键完成容器化部署需要稳定、快捷上线的生产用户基本 Linux 操作经验使用脚本部署 KaiwuDB
可视化向导提供图形界面和分步向导，操作直观初学者或偏好图形化操作的用户图形化桌面环境使用可视化向导部署 KaiwuDB
容器镜像部署 - Docker Compose基于 YAML 文件进行编排部署，目前仅支持非安全模式熟悉容器编排的用户，适合测试或快速验证具备 Docker & Compose 基础使用 YAML 文件部署 KaiwuDB
容器镜像部署 - Docker Run使用 docker run 命令直接运行容器适合测试、快速验证熟悉 Docker 命令行操作执行 Docker Run 命令部署 KaiwuDB

提示

KaiwuDB 支持两种单机主备高可用性方案：

如果您计划实施基于 DRBD 的高可用方案，请先参阅基于 DRBD 的单机高可用性方案。

部署准备

硬件

下表列出部署 KaiwuDB 所需的硬件规格。

项目要求
CPU 和内存单节点配置建议不低于 4 核 8G。对于数据量大、复杂的工作负载、高并发和高性能场景，建议配置更高的 CPU 和内存资源以确保系统的高效运行。
磁盘- 推荐使用 SSD 或者 NVMe 设备，尽量避免使用 NFS、CIFS、CEPH 等共享存储。
- 磁盘必须能够实现 500 IOPS 和 30 MB/s 处理效率。
- KaiwuDB 系统自身启动不会占用过多磁盘容量（低于 1G）。实际所需磁盘大小主要取决于用户的业务量。实际部署时，用户可以根据实际的业务规模和性能要求规划硬件资源。更多详细信息，参见预估磁盘使用量。
文件系统建议使用 ext4 文件系统。

操作系统

说明

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

操作系统版本ARM_64x86_64
Anolis7✓✓
8✓✓
CentOS7✓
8✓
DebianV11✓
KylinOSV10 SP2✓✓
V10 SP3 2403✓✓
openEuler24.03✓
UbuntuV20.04✓✓
V22.04✓✓
V24.04✓✓
UOS1050e✓✓
1060e✓✓
1070e✓✓
Windows ServerWSL2✓

软件依赖（可选）

如采用安装脚本或 YAML 文件部署 KaiwuDB, 目标机器需已安装 Docker Compose（1.20.0 及以上版本）。

sudo apt-get install docker-compose

端口要求

下表列出 KaiwuDB 服务默认使用的端口。在安装部署前，确保目标机器的以下端口没有被占用且没有被防火墙拦截。如需使用其他端口，可在安装部署过程中进行修改。

端口号说明
8080数据库 Web 服务端口
26257数据库服务端口和对外连接端口

安装包和可视化安装程序

根据不同的使用场景，获取安装包或可视化安装程序：

  • 安装包：适用于生产环境部署和具备 Linux 操作经验的用户。支持脚本部署、YAML 文件部署和 Docker Run 命令部署，可灵活配置集群参数，具备完整的命令行管理功能。
  • 可视化安装程序：适用于初学者和偏好图形化操作的用户。通过直观的向导界面简化部署流程，降低技术门槛，使用前需确保目标机器具备图形化桌面环境支持。

安装包

获取系统环境对应的安装包，将安装包复制到待安装 KaiwuDB 的目标机器上，然后解压缩安装包：

tar -zxvf <install_package_name>

解压后生成的目录包含以下文件：

文件说明
add_user.sh安装、启动 KaiwuDB 后，为 KaiwuDB 数据库创建用户。
deploy.cfg安装部署配置文件，用于配置部署节点的 IP 地址、端口等配置信息。
deploy.sh安装部署脚本，用于安装、卸载、启动、状态获取、关停和重启等操作。
packages 目录存放镜像包。
utils 目录存放工具类脚本。

可视化安装程序

获取系统环境对应的可视化向导安装程序（.AppImage 格式），复制到待安装 KaiwuDB 的目标机器上。

部署 KaiwuDB

使用脚本部署 KaiwuDB

使用脚本部署 KaiwuDB 时，系统将对配置文件、运行环境、硬件配置和软件依赖进行检查。如果相应硬件未能满足要求，系统将继续安装，并提示硬件规格不满足要求。如果软件依赖未能满足要求，系统将中止安装，并提供相应的提示信息。

在部署过程中，系统会自动生成相关日志。如果部署时出现错误，用户可以通过查看终端输出或 KaiwuDB 安装目录中 log 目录里的日志文件，获取详细的错误信息。

部署完成后，系统生成 /etc/kaiwudb/ 目录。Docker Compose 配置文件 docker-compose.yml 位于 /etc/kaiwudb/script 目录下。部署完成后，用户可以修改 Docker Compose 配置文件 docker-compose.yml，配置 KaiwuDB 的启动参数和 CPU 资源占用率。有关定制化部署配置的详细信息，参见配置集群。

前提条件：

  • 已获取 KaiwuDB 容器安装包。
  • 待部署节点的硬件、操作系统、软件依赖和端口满足安装部署要求。
  • 安装用户为 root 用户或者拥有 sudo 权限的普通用户。
    • root 用户和配置 sudo 免密的普通用户在执行部署脚本时无需输入密码。
    • 未配置 sudo 免密的普通用户在执行部署脚本时，需要输入密码进行提权。
  • 安装用户为非 root 用户时，需要通过 sudo usermod -aG docker $USER 命令将用户添加到 docker 组。

步骤：

如需使用脚本部署 KaiwuDB，遵循以下步骤。

  1. 登录待部署节点，编辑安装包目录下的 deploy.cfg 配置文件，设置安全模式、管理用户、服务端口等信息。

    说明

    默认情况下，deploy.cfg 配置文件中包含集群配置参数。请删除或注释 [cluster] 集群配置项。

    配置文件示例：

    [global]
secure_mode=tls
management_user=kaiwudb
rest_port=8080
kaiwudb_port=26257
# brpc_port=27257
data_root=/var/lib/kaiwudb
cpu=1
encrypto_store=true

[local]
node_addr=your-host-ip

# [cluster]
# node_addr=your-host-ip, your-host-ip
# ssh_port=22
# ssh_user=admin

    参数说明：

    • global：全局配置
      • secure_mode：是否开启安全模式，支持以下三种取值：
        • insecure：使用非安全模式。
        • tls：（默认选项）开启 TLS 安全模式。开启安全模式后，KaiwuDB 生成 TLS 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
        • tlcp：开启 TLCP 安全模式。开启安全模式后，KaiwuDB 生成 TLCP 证书，作为客户端或应用程序连接数据库的凭证。生成的客户端相关证书存放在 /etc/kaiwudb/certs 目录。
      • management_user：KaiwuDB 的管理用户，默认为 kaiwudb。安装部署后，KaiwuDB 创建相应的管理用户以及和管理用户同名的用户组。
      • rest_port：KaiwuDB Web 服务端口，默认为 8080。
      • kaiwudb_port：KaiwuDB 服务端口，默认为 26257。
      • brpc_port：KaiwuDB 时序引擎间的 brpc 通信端口，用于节点间通信。单节点部署时可不指定，指定后系统会自动忽略该设置。
      • data_root：数据目录，默认为 /var/lib/kaiwudb。
      • cpu: 可选参数，用于指定 KaiwuDB 服务占用当前节点服务器 CPU 资源的比例，默认无限制。取值范围为 [0,1]，最大精度为小数点后两位。
      • encrypto_store: 可选参数，用于在部署时启用关系数据库存储加密功能。默认情况下，该参数不会显示，需要用户手动添加到配置文件中并设置为 true。启用后，系统将在 /etc/kaiwudb/certs 目录下自动生成存储密钥，使用 SM4 加密算法对数据进行加密。KaiwuDB 支持通过 --store-encryption 启动参数，在部署后进行目录加密、解密、存储密钥更新和算法更换等操作，更多信息，参见存储加密。
    • local：本地节点配置
      • node_addr：本地节点对外提供服务的 IP 地址，监听地址为 0.0.0.0，端口为 KaiwuDB 服务端口。

  2. 为 deploy.sh 脚本添加运行权限。

    chmod +x ./deploy.sh

  3. 执行单机部署安装命令。

    ./deploy.sh install --single

    执行成功后，控制台输出以下信息：

    INSTALL COMPLETED: KaiwuDB has been installed successfuly! ...

  4. 根据系统提示重新加载 systemd 守护进程的配置文件。

    systemctl daemon-reload

  5. 启动 KaiwuDB 节点。

    ./deploy.sh start

    执行成功后，控制台输出以下信息：

    START COMPLETED: KaiwuDB has started successfuly.

  6. 查看 KaiwuDB 节点状态。

    ./deploy.sh status

    或者

    systemctl status kaiwudb

  7. （可选）配置 KaiwuDB 开机自启动。

    配置 KaiwuDB 开机自启动后，如果系统重启，则自动启动 KaiwuDB。

    systemctl enable kaiwudb

  8. （可选）执行 add_user.sh 脚本创建数据库用户。如果跳过该步骤，系统将默认使用部署数据库时使用的用户，且无需密码访问数据库。

    ./add_user.sh
Please enter the username: 
Please enter the password:

    执行成功后，控制台输出以下信息：

    [ADD USER COMPLETED]:User creation completed.

使用可视化向导部署 KaiwuDB

可视化向导提供图形化的部署界面，简化配置过程。系统同样会对配置文件、运行环境、硬件配置和软件依赖进行检查。

如果部署时出现错误，用户可以通过查看终端输出、界面提示或安装目录中的日志文件，获取详细的错误信息。

前提条件

  • 待部署节点的硬件、操作系统、软件依赖和端口满足安装部署要求。
  • 安装用户为 root 用户或者拥有 sudo 权限的普通用户。
    • root 用户和配置 sudo 免密的普通用户在执行部署脚本时无需输入密码。
    • 未配置 sudo 免密的普通用户在执行部署脚本时，需要输入密码进行提权。
  • 安装用户为非 root 用户时，需要通过 sudo usermod -aG docker $USER 命令将用户添加到 docker 组。
  • 已获取对应系统版本的 KaiwuDB 可视化向导安装程序（.AppImage 格式）。

步骤

如需部署 KaiwuDB，遵循以下步骤。

  1. 登录待部署节点，复制安装程序到安装目录。

  2. 为安装程序添加执行权限：

    chmod +x KaiwuDB-*.AppImage

  3. 使用以下命令或双击启动安装程序：

    • root 用户

      ./KaiwuDB-*.AppImage

    • 普通用户

      sudo ./KaiwuDB-*.AppImage

  4. 在欢迎页面点击下一步。

  5. 在操作选择页面，点击下一步。

  6. 在参数配置页面，设置以下参数，然后点击下一步：

    • 安全模式选项：启用后，KaiwuDB 将自动生成证书，存放在 /etc/kaiwudb/certs 目录，作为客户端或应用程序连接数据库的凭证
    • 服务端口
    • HTTP 端口
    • bRPC 端口
    • 数据目录
    • 用户创建选项：如果跳过，系统将默认使用部署数据库时的用户，且无需密码访问数据库

  7. 在部署模式页面，勾选单机模式，点击设置本机IP, 完成节点 IP 地址后，点击下一步，系统将自动跳转至安装页面。

  8. 在安装页面，等待安装完成，然后根据需要选择：

    • 点击下一步，进入数据库参数页面。

    • 设置启动参数, 然后点击提交。KaiwuDB 支持设置多个启动参数，用空格分隔。支持的参数列表参见kwbase start-single-node。

    • 安装页面

    • 设置启动参数窗口

  9. （可选）在数据库参数页面，点击输入license, 在许可证验证窗口输入许可证代码，然后点击提交。

  10. （可选）点击设置集群参数按钮，根据需要设置集群参数值。KaiwuDB 支持的集群参数列表参见实时参数。

  11. 点击结束完成部署。部署完成后，即可进行以下操作：

    • （可选）配置 KaiwuDB 开机自启动

      systemctl enable kaiwudb

    • 通过 sudo docker exec -it kaiwudb-container /bin/bash 进入容器，使用 kwbase 命令或使用其他方式连接和管理 KaiwuDB。

使用 YAML 文件部署 KaiwuDB

前提条件：

  • 已获取 KaiwuDB 容器安装包。
  • 待部署节点的硬件、操作系统、软件依赖和端口满足安装部署要求。
  • 安装用户为 root 用户或者拥有 sudo 权限的普通用户。
    • root 用户和配置 sudo 免密的普通用户在执行部署脚本时无需输入密码。
    • 未配置 sudo 免密的普通用户在执行部署脚本时，需要输入密码进行提权。
  • 安装用户为非 root 用户时，需要通过 sudo usermod -aG docker $USER 命令将用户添加到 docker 组。

步骤：

如需使用 YAML 文件部署 KaiwuDB，遵循以下步骤。

  1. 在 kaiwudb_install/packages 目录下导入 KaiwuDB.tar 文件，获取镜像名称。

    docker load < KaiwuDB.tar
Loaded image: "$kaiwudb_image"

  2. 创建 docker-compose.yml 配置文件。

    说明

    image 参数的取值必须是导入 KaiwuDB.tar 文件后获取的镜像名称。

    配置文件示例：

    version: '3.3'
services:
  kaiwudb-container:
    image: "$kaiwudb_image"
    container_name: kaiwudb-experience
    hostname: kaiwudb-experience
    ports:
      - 8080:8080
      - 26257:26257
    ulimits:
      memlock: -1
    networks: 
      - default
    restart: on-failure
    ipc: shareable
    privileged: true
    environment:
      - LD_LIBRARY_PATH=/kaiwudb/lib
    tty: true
    working_dir: /kaiwudb/bin
    command: 
      - /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

  3. 快速启动 KaiwuDB。

    docker-compose up -d

执行 Docker Run 命令部署 KaiwuDB

前提条件：

  • 已获取 KaiwuDB 容器安装包。
  • 待部署节点的硬件、操作系统、软件依赖和端口满足安装部署要求。
  • 安装用户为 root 用户或者拥有 sudo 权限的普通用户。
    • root 用户和配置 sudo 免密的普通用户在执行部署脚本时无需输入密码。
    • 未配置 sudo 免密的普通用户在执行部署脚本时，需要输入密码进行提权。
  • 安装用户为非 root 用户时，需要通过 sudo usermod -aG docker $USER 命令将用户添加到 docker 组。

步骤：

  1. 在 kaiwudb_install/packages 目录下导入 KaiwuDB.tar 文件，获取镜像名称。

    docker load < KaiwuDB.tar
Loaded image: "$kaiwudb_image"

  2. （可选）如需以安全模式部署 KaiwuDB, 使用以下命令创建数据库证书颁发机构、root 用户的客户端证书以及节点服务器证书。

    • TLS 安全模式

      docker run --rm --privileged \
  -v /etc/kaiwudb/certs:/kaiwudb/certs \
  -w /kaiwudb/bin \
  $kaiwudb_image \
  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 --certs-dir=/kaiwudb/certs --ca-key=/kaiwudb/certs/ca.key'

    • TLCP 安全模式

      docker run --rm --privileged \
 -v /etc/kaiwudb/certs:/kaiwudb/certs \
 -w /kaiwudb/bin \
 $kaiwudb_image \
 bash -c './kwbase cert create-ca --certs-dir=/kaiwudb/certs --ca-key=/kaiwudb/certs/ca.key --tlcp && \
          ./kwbase cert create-client root --certs-dir=/kaiwudb/certs --ca-key=/kaiwudb/certs/ca.key --tlcp && \
          ./kwbase cert create-node 127.0.0.1 localhost 0.0.0.0 --certs-dir=/kaiwudb/certs --ca-key=/kaiwudb/certs/ca.key --tlcp'

    参数说明：

    • --rm：容器停止后自动删除。
    • --privileged：给予容器扩展权限。
    • -v：设置容器目录映射, 将主机的 /etc/kaiwudb/certs 目录挂载到容器内的 /kaiwudb/certs 目录，用于存放证书和密钥。
    • -w /kaiwudb/bin：将容器内的工作目录设置为 /kaiwudb/bin。
    • $kaiwudb_image：容器镜像，需填入实际的镜像名以及标签, 例如 kaiwudb:2.2.0。
    • bash -c：在容器中执行后面的证书创建命令, 其中：
      • ./kwbase cert create-ca: 创建证书颁发机构(CA)，生成 CA 证书和密钥。
      • ./kwbase cert create-client root: 为 root 用户创建客户端证书和密钥。
      • ./kwbase cert create-node 127.0.0.1 localhost 0.0.0.0: 创建节点证书和密钥，支持通过三种网络标识符访问：本地回环地址 (127.0.0.1)、本地主机名 (localhost) 和所有网络接口 (0.0.0.0)。
      • 所有命令均使用 --certs-dir=/kaiwudb/certs 指定证书存储目录，使用 --ca-key=/kaiwudb/certs/ca.key 指定密钥路径。
      • TLCP 安全模式下需通过 --tlcp 参数指定使用 TLCP 协议的证书生成方式。

  3. 启动 KaiwuDB 数据库。

    • 非安全模式

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

    • TLS 安全模式

      docker run -d --privileged --name kaiwudb \
--ulimit memlock=-1 \
--ulimit nofile=$max_files \
-p $db_port:26257 \
-p $http_port:8080 \
-v /etc/kaiwudb/certs:/kaiwudb/certs \
-v /var/lib/kaiwudb:/kaiwudb/deploy/kaiwudb-container \
--ipc shareable \
-w /kaiwudb/bin \
$kaiwudb_image \
./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

    • TLCP 安全模式

      docker run -d --privileged --name kwdb \
--ulimit memlock=-1 \
--ulimit nofile=$max_files \
-p $db_port:26257 \
-p $http_port:8080 \
-v /etc/kaiwudb/certs:/kaiwudb/certs \
-v /var/lib/kaiwudb:/kaiwudb/deploy/kaiwudb-container \
--ipc shareable \
-w /kaiwudb/bin \
$kaiwudb_image \
./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 \
  --tlcp

    参数说明：

    • -d：后台运行容器并返回容器 ID。
    • --name kaiwudb：指定容器名称为 kaiwudb，便于后续管理。
    • --privileged：给予容器扩展权限。
    • --ulimit memlock=-1：取消容器内存大小限制。
    • --ulimit nofile=$max_files：设置容器内进程可以打开的最大文件数。
    • -p $db_port:26257：将容器的 26257 端口(数据库主端口)映射到主机的指定端口。
    • -p $http_port:8080: 将容器的 8080 端口(HTTP 端口)映射到主机的指定端口。
    • -v：设置容器目录映射：
      • 将主机的 /var/lib/kaiwudb 目录挂载到容器内的 /kaiwudb/deploy/kaiwudb-container 目录，用于持久化数据存储。
      • 安全模式下，将主机的 /etc/kaiwudb/certs 目录挂载到容器内的 /kaiwudb/certs 目录，用于存放证书和密钥。
    • --ipc shareable：允许其他容器共享此容器的IPC命名空间。
    • -w /kaiwudb/bin：将容器内的工作目录设置为 /kaiwudb/bin。
    • $kaiwudb_image：容器镜像变量，需替换为实际的镜像名称及标签, 例如 kaiwudb:2.2.0。
    • ./kwbase start: 容器内运行的数据库启动命令, 根据安全模式和非安全模式有所不同:
      • --insecure：（仅非安全模式）指定以非安全模式运行。
      • --certs-dir=/kaiwudb/certs：（安全模式）指定证书目录位置。
      • --listen-addr=0.0.0.0:26257：指定数据库监听的地址和端口。
      • --http-addr=0.0.0.0:8080：指定 HTTP 接口监听的地址和端口。
      • --store=/kaiwudb/deploy/kaiwudb-container：指定数据存储位置。
      • --tlcp：（TLCP 安全模式）使用 TLCP 加密协议。

  4. （可选）创建数据库用户并授予用户管理员权限。如果跳过该步骤，系统将默认使用部署数据库时的用户，且无需密码访问数据库。

    • 非安全模式（不带密码）：

      docker exec kaiwudb-container bash -c "./kwbase sql --insecure --host=$host_ip -e \"create user $user_name;grant admin to $user_name with admin option;\""

    • TLS 安全模式（带密码）：

      docker exec kaiwudb-container bash -c "./kwbase sql --host=$host_ip --certs-dir=$cert_path -e \"create user $user_name with password \\\"$user_password\\\";grant admin to $user_name with admin option;\""

    • TLCP 安全模式（带密码）：

      docker exec kaiwudb-container bash -c "./kwbase sql --host=$host_ip --certs-dir=$cert_path --tlcp -e \"create user $user_name with password \\\"$user_password\\\";grant admin to $user_name with admin option;\""

配置许可证

KaiwuDB 数据库集群启动后，只有具有 admin 权限的管理员可以登录数据库并通过 cluster.license 集群参数将许可证添加到已启动的集群中。成功启动 KaiwuDB 集群后，如果集群中的当前节点数量未超过许可证限制的节点数量时，用户可以设置许可证成功。否则，用户设置许可证失败。此时，用户需要先缩容集群，等节点数量满足许可证要求后，方可成功设置许可证。数据库会自动检查许可证的有效性。如果有效，则激活集群并允许其他用户登录。否则，将拒绝其他用户登录。有关许可证管理的详细信息，参见许可证管理。

说明

如果使用可视化向导部署的用户在部署过程中已完成许可证配置，可跳过此章节。

  1. 联系open in new window KaiwuDB 技术支持人员，获取 .lic 格式的 KaiwuDB 许可证文件。

  2. 复制文件中的许可证码，通过以下命令将许可证码添加到已启动的数据库中。

    SET CLUSTER SETTING cluster.license = '<your-license-code>';

    其中，your-license-code 应替换为从 .lic 文件中提取的许可证码。有关 cluster.license 参数的详细信息，参见集群实时参数。

  3. （可选）查看许可证信息。

    SHOW LICENSE;

    用户也可以通过 kwdb_internal.kwdb_license 系统视图查看许可证信息。有关详细信息，参见系统视图。

  4. （可选）更新许可证。

    许可证过期后，只有具有 admin 权限的管理员可以登录数据库并通过 cluster.license 参数更新许可证。