单节点裸机部署
KaiwuDB 支持多种单节点裸机部署方式，以满足不同用户的部署需求：
| 部署方式 | 特点 | 适用用户 | 技术要求 | 详细指南 |
|---|---|---|---|---|
| 脚本部署（推荐） | 一键部署，内置故障检测，适合生产环境快速上线 | 需要稳定、快捷上线的生产用户 | 具备基本的 Linux 操作经验 | 使用脚本部署 KaiwuDB |
| 可视化向导 | 提供图形界面和分步向导，操作直观 | 初学者或偏好图形化操作的用户 | 需要具备图形化桌面环境 | 使用可视化向导部署 KaiwuDB |
| CLI 命令行 | 支持精细化控制和深度定制 | 有经验的资深用户，定制化需求场景 | 熟悉数据库部署流程和命令行操作 | 使用 kwbase CLI 部署 KaiwuDB |
部署准备
硬件
下表列出部署 KaiwuDB 所需的硬件规格。
| 项目 | 要求 |
|---|---|
| CPU 和内存 | 单节点配置建议不低于 4 核 8G。对于数据量大、复杂的工作负载、高并发和高性能场景，建议配置更高的 CPU 和内存资源以确保系统的高效运行。 |
| 磁盘 | - 推荐使用 SSD 或者 NVMe 设备，尽量避免使用 NFS、CIFS、CEPH 等共享存储。 - 磁盘必须能够实现 500 IOPS 和 30 MB/s 处理效率。 - KaiwuDB 系统自身启动不会占用过多磁盘容量（低于 1G）。实际所需磁盘大小主要取决于用户的业务量。实际部署时，用户可以根据实际的业务规模和性能要求规划硬件资源。更多详细信息，参见预估磁盘使用量。 |
| 文件系统 | 建议使用 ext4 文件系统。 |
操作系统
KaiwuDB 支持在以下服务器操作系统进行安装部署。
| 操作系统 | 版本 | ARM_64 | x86_64 |
|---|---|---|---|
| Anolis | 8 | ✓ | ✓ |
| KylinOS | V10 SP2 | ✓ | ✓ |
| V10 SP3 2403 | ✓ | ✓ | |
| Ubuntu | V20.04 | ✓ | ✓ |
| V22.04 | ✓ | ✓ | |
| V24.04 | ✓ | ✓ | |
| UOS | 1070e | ✓ | ✓ |
| Windows Server | WSL2 | ✓ |
说明
未提及的操作系统和版本也许可以运行 KaiwuDB，但尚未得到 KaiwuDB 官方支持。
软件依赖
安装时，KaiwuDB 会对依赖进行检查。如果缺少依赖会退出安装并提示依赖缺失。如果目标机器不能联网，用户需要在能联网的机器上根据目标机器的操作系统下载好所有依赖文件，然后将依赖文件复制到目标机器上进行安装。
下表列出需要在目标机器安装的依赖：
| 依赖 | 版本 | 说明 |
|---|---|---|
| OpenSSL | v1.1.1+ | N/A |
| libprotobuf | v3.6.1+ | Ubuntu 18.04 版本默认的 libprotobuf 版本低于所需版本，用户需要在部署前提前安装高版本的 libprotobuf 或者使用安装包内提供的高版本 libprotobuf 完成安装。具体操作说明，参见libprotobuf 安装。 |
| GEOS | v3.3.8+ | 可选依赖 |
| xz-libs | v5.2.0+ | N/A |
| libgcc | v7.3.0+ | N/A |
端口要求
下表列出 KaiwuDB 服务默认使用的端口。在安装部署前，确保目标机器的以下端口没有被占用且没有被防火墙拦截。如需使用其他端口，可在安装部署过程中进行修改。
| 端口号 | 说明 |
|---|---|
8080 | 数据库 Web 服务端口 |
26257 | 数据库服务端口和对外连接端口 |
安装包和可视化安装程序
根据不同的使用场景，获取安装包或可视化安装程序：
- 安装包：适用于生产环境部署和具备 Linux 操作经验的用户。支持脚本部署和 kwbase CLI 部署两种方式，可灵活配置集群参数，具备完整的命令行管理功能。
- 可视化安装程序：适用于初学者和偏好图形化操作的用户。通过直观的向导界面简化部署流程，降低技术门槛，使用前需确保目标机器具备图形化桌面环境支持。
安装包
获取系统环境对应的 DEB 或 RPM 安装包，将安装包复制到待安装 KaiwuDB 的目标机器上，然后解压缩安装包：
tar -zxvf <package_name>
解压后生成的目录包含以下文件：
| 文件 | 说明 |
|---|---|
add_user.sh | 安装、启动 KaiwuDB 后，为 KaiwuDB 数据库创建用户。 |
deploy.cfg | 安装部署配置文件，用于配置部署节点的 IP 地址、端口等配置信息。 |
deploy.sh | 安装部署脚本，用于安装、卸载、启动、状态获取、关停和重启等操作。 |
packages 目录 | 存放 DEB、RPM、镜像包和 libprotobuf 包。 |
utils 目录 | 存放工具类脚本。 |
可视化安装程序
获取系统环境对应的可视化向导安装程序（.AppImage 格式），复制到待安装 KaiwuDB 的目标机器上。
libprotobuf 安装
说明
以下步骤仅适用于 Ubuntu 18.04 操作系统。
检查当前系统中是否已安装 libprotobuf 及其版本是否符合要求（3.6.1 及以上版本）。
dpkg -l | grep libprotobuf
如果未安装 libprotobuf，手动安装
packages目录下的 libprotobuf 文件。dpkg -i ./libprotobuf23_3.12.4_amd64.deb如果系统中已经安装了 libprotobuf，但版本低于 3.6.1：
查看 libprotobuf 版本的相关依赖：
apt-cache rdepends <libprotobuf_package>确认没有其他重要包依赖于当前版本后，手动安装
packages目录下的 libprotobuf 文件。dpkg -i ./libprotobuf23_3.12.4_amd64.deb
部署 KaiwuDB
使用脚本部署 KaiwuDB
使用脚本部署 KaiwuDB 时，系统将对配置文件、运行环境、硬件配置和软件依赖进行检查。如果相应硬件未能满足要求，系统将继续安装，并提示硬件规格不满足要求。如果软件依赖未能满足要求，系统将中止安装，并提供相应的提示信息。
在部署过程中，系统会自动生成相关日志。如果部署时出现错误，用户可以通过查看终端输出或 KaiwuDB 安装目录中 log 目录里的日志文件，获取详细的错误信息。
部署完成后，系统会将 KaiwuDB 封装成系统服务（名称为 kaiwudb），并生成以下文件：
kaiwudb.service：配置 KaiwuDB 的 CPU 资源占用率。kaiwudb_env：配置 KaiwuDB 启动参数。
前提条件
- 待部署节点的硬件、操作系统、软件依赖和端口满足安装部署要求。
- 安装用户为 root 用户或者拥有
sudo权限的普通用户。- root 用户和配置
sudo免密的普通用户在执行部署脚本时无需输入密码。 - 未配置
sudo免密的普通用户在执行部署脚本时，需要输入密码进行提权。
- root 用户和配置
步骤
如需部署 KaiwuDB，遵循以下步骤。
登录待部署节点，编辑安装包目录下的
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]，最大精度为小数点后两位。注意：如果部署环境为 Ubuntu 18.04 版本，部署完成后，需要将kaiwudb.service文件中的CPUQuota修改为整型值，例如，将180.0%修改为180%，以确保设置生效。具体操作步骤，参见配置 CPU 资源占用率。encrypto_store: 可选参数，用于在部署时启用关系数据库存储加密功能。默认情况下，该参数不会显示，需要用户手动添加到配置文件中并设置为true。启用后，系统将在/etc/kaiwudb/certs目录下自动生成存储密钥，使用 SM4 加密算法对数据进行加密。KaiwuDB 支持通过--store-encryption启动参数，在部署后进行目录加密、解密、存储密钥更新和算法更换等操作，更多信息，参见存储加密。
local：本地节点配置node_addr：本地节点对外提供服务的 IP 地址，监听地址为0.0.0.0，端口为 KaiwuDB 服务端口。
为
deploy.sh脚本添加运行权限。chmod +x ./deploy.sh执行单机部署安装命令。
./deploy.sh install --single执行成功后，控制台输出以下信息：
INSTALL COMPLETED: KaiwuDB has been installed successfuly! ...根据系统提示重新加载
systemd守护进程的配置文件。systemctl daemon-reload启动 KaiwuDB 节点。
./deploy.sh start执行成功后，控制台输出以下信息：
START COMPLETED: KaiwuDB has started successfuly.查看 KaiwuDB 节点状态。
./deploy.sh status或者
systemctl status kaiwudb（可选）配置 KaiwuDB 开机自启动。
配置 KaiwuDB 开机自启动后，如果系统重启，则自动启动 KaiwuDB。
systemctl enable kaiwudb（可选）执行
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 用户和配置
- 已获取对应系统版本的 KaiwuDB 可视化向导安装程序（.AppImage 格式）。
步骤
如需部署 KaiwuDB，遵循以下步骤。
登录待部署节点，复制安装程序到安装目录。
为安装程序添加执行权限：
chmod +x KaiwuDB-*.AppImage使用以下命令或双击启动安装程序：
root 用户
./KaiwuDB-*.AppImage普通用户
sudo ./KaiwuDB-*.AppImage
在欢迎页面点击下一步。
在操作选择页面，点击下一步。
在参数配置页面，设置以下参数，然后点击下一步：
- 安全模式选项：启用后，KaiwuDB 将自动生成证书，存放在
/etc/kaiwudb/certs目录，作为客户端或应用程序连接数据库的凭证 - 服务端口
- HTTP 端口
- bRPC 端口
- 数据目录
- 用户创建选项：如果跳过，系统将默认使用部署数据库时的用户，且无需密码访问数据库
- 安全模式选项：启用后，KaiwuDB 将自动生成证书，存放在
在部署模式页面，勾选单机模式，点击设置本机IP, 完成节点 IP 地址后，点击下一步，系统将自动跳转至安装页面。
在安装页面，等待安装完成，然后根据需要选择：
点击下一步，进入数据库参数页面。
设置启动参数, 然后点击提交。KaiwuDB 支持设置多个启动参数，用空格分隔。支持的参数列表参见kwbase start-single-node。
安装页面
设置启动参数窗口
（可选）在数据库参数页面，点击输入license, 在许可证验证窗口输入许可证代码，然后点击提交。
（可选）点击设置集群参数按钮，根据需要设置集群参数值。KaiwuDB 支持的集群参数列表参见实时参数。
点击结束完成部署。部署完成后，即可进行以下操作：
（可选）配置 KaiwuDB 开机自启动
systemctl enable kaiwudb切换至
user/local/kaiwudb/bin目录，使用 kwbase 命令或使用其他方式连接和管理 KaiwuDB。
使用 kwbase CLI 部署 KaiwuDB
前提条件
- 待部署节点的硬件配置、操作系统、软件依赖和端口满足安装部署要求
- 安装用户为
root用户或拥有sudo权限的普通用户
步骤
登录待部署节点，进入安装包目录下的
packages目录。安装依赖包和服务器组件。
DEB 包系统（Debian/Ubuntu）：
dpkg -i ./kaiwudb-libcommon-<版本号>.deb ./kaiwudb-server-<版本号>.debRPM 包系统（CentOS/RHEL）：
rpm -ivh ./kaiwudb-libcommon-<版本号>.rpm ./kaiwudb-server-<版本号>.rpm
切换至程序目录：
cd /usr/local/kaiwudb/bin(可选）如需采用安全部署模式，执行以下步骤创建证书：
创建证书存放目录：
mkdir -p /usr/local/kaiwudb/certs生成证书和密钥。
TLS 安全模式：
# 创建数据库证书颁发机构及密钥 ./kwbase cert create-ca --certs-dir=/usr/local/kaiwudb/certs --ca-key=/usr/local/kaiwudb/certs/ca.key && \ # 创建安装数据库用户的客户端证书及密钥（USER_NAME 替换为实际用户名） ./kwbase cert create-client $USERNAME --certs-dir=/usr/local/kaiwudb/certs --ca-key=/usr/local/kaiwudb/certs/ca.key && \ # 创建节点服务器证书及密钥 ./kwbase cert create-node 127.0.0.1 localhost 0.0.0.0 --certs-dir=/usr/local/kaiwudb/certs --ca-key=/usr/local/kaiwudb/certs/ca.keyTLCP 安全模式：
# 创建数据库证书颁发机构及密钥 ./kwbase cert create-ca --certs-dir=/usr/local/kaiwudb/certs --ca-key=/usr/local/kaiwudb/certs/ca.key --tlcp && \ # 创建安装数据库用户的客户端证书及密钥（USER_NAME 替换为实际用户名） ./kwbase cert create-client $USERNAME --certs-dir=/usr/local/kaiwudb/certs --ca-key=/usr/local/kaiwudb/certs/ca.key --tlcp && \ # 创建节点服务器证书及密钥 ./kwbase cert create-node 127.0.0.1 localhost 0.0.0.0 --certs-dir=/usr/local/kaiwudb/certs --ca-key=/usr/local/kaiwudb/certs/ca.key --tlcp
启动数据库。
非安全模式：
./kwbase start-single-node --insecure \ --listen-addr=0.0.0.0:26257 \ --http-addr=0.0.0.0:8080 \ --store=/var/lib/kaiwudbTLS 安全模式：
./kwbase start-single-node \ --certs-dir=/usr/local/kaiwudb/certs \ --listen-addr=0.0.0.0:26257 \ --http-addr=0.0.0.0:8080 \ --store=/var/lib/kaiwudbTLCP 安全模式：
./kwbase start-single-node \ --certs-dir=/usr/local/kaiwudb/certs \ --listen-addr=0.0.0.0:26257 \ --http-addr=0.0.0.0:8080 \ --store=/var/lib/kaiwudb \ --tlcp
查看数据库状态。
非安全模式：
./kwbase node status --insecure --host=<address_of_any_alive_node>TLS 安全模式：
./kwbase node status --certs-dir=/usr/local/kaiwudb/certs --host=<address_of_any_alive_node>TLCP 安全模式：
./kwbase node status --certs-dir=/usr/local/kaiwudb/certs --host=<address_of_any_alive_node> --tlcp
（可选）创建数据库用户并授予用户管理员权限。如果跳过该步骤，系统将默认使用部署数据库时的用户，且无需密码访问数据库。
非安全模式（不带密码）：
./kwbase sql --host=127.0.0.1:$(local_port) --insecure \ -e "create user $user_name; \ grant admin to $user_name with admin option;"TLS 安全模式（带密码）：
./kwbase sql --certs-dir=/usr/local/kaiwudb/certs --host=127.0.0.1:$(local_port) \ -e "create user $user_name with password \"$user_password\"; \ grant admin to $user_name with admin option;"TLCP 安全模式（带密码）：
./kwbase sql --certs-dir=/usr/local/kaiwudb/certs --tlcp --host=127.0.0.1:$(local_port) \ -e "create user $user_name with password \"$user_password\"; \ grant admin to $user_name with admin option;"
配置许可证
KaiwuDB 数据库启动后，只有具有 admin 权限的管理员可以登录数据库并通过 cluster.license 集群参数添加许可证。成功启动 KaiwuDB 后，如果数据库当前节点数量未超过许可证限制的节点数量，用户可以设置许可证成功。否则，用户设置许可证失败。数据库会自动检查许可证的有效性。如果有效，则激活服务并允许其他用户登录。否则，将拒绝其他用户登录。有关许可证管理的详细信息，参见许可证管理。
说明
如果使用可视化向导部署的用户在部署过程中已完成许可证配置，可跳过此章节。
联系 KaiwuDB 技术支持人员，获取
.lic格式的 KaiwuDB 许可证文件。复制文件中的许可证码，通过以下命令将许可证码添加到已启动的数据库中。
SET CLUSTER SETTING cluster.license = '<your-license-code>';其中，
your-license-code应替换为从.lic文件中提取的许可证码。有关cluster.license参数的详细信息，参见集群实时参数。（可选）查看许可证信息。
SHOW LICENSE;用户也可以通过
kwdb_internal.kwdb_license系统视图查看许可证信息。有关详细信息，参见系统视图。（可选）更新许可证。
许可证过期后，只有具有
admin权限的管理员可以登录数据库并通过cluster.license参数更新许可证。