KaiwuDB社区版 3.1.0 在 Ubuntu 22.04 部署实战：TLS 配置、踩坑复盘与轻量压测

倔强的石头1062026-03-26 21:07

KWDB 作为一款易用性不断优化的数据库产品，其 3.1.0 版本在运维脚本、配置管理等方面的升级为部署带来了便利，但新手在单机部署过程中仍易因环境适配、依赖缺失、配置不当等问题踩坑。为帮助开发者快速落地 KWDB 单机环境，本文以 Ubuntu 22.04 为基础环境，从实战角度出发，完整拆解 KWDB 3.1.0 单机部署的全流程：不仅明确版本选型依据和部署目标，还细化了环境核查、安装包获取、依赖配置、部署脚本执行等关键操作，针对性解决部署中的高频问题，并通过服务验证、性能基线测试完成最小化验收，最终实现 "安装即能用、问题有解法、效果可验证" 的部署目标，为 KWDB 入门者提供清晰、可复现的实操指引。

文章目录

    • [1. 版本与部署路线怎么选](#1. 版本与部署路线怎么选)
    • [2. 目标：这篇文章读完，能带走哪些"干货"？](#2. 目标：这篇文章读完，能带走哪些“干货”？)
    • [3. 开干前的准备工作](#3. 开干前的准备工作)
      • [3.1 摸底系统信息](#3.1 摸底系统信息)
      • [3.2 查查端口有没有被占](#3.2 查查端口有没有被占)
      • [3.3 规划一下目录（墙裂推荐）](#3.3 规划一下目录（墙裂推荐）)
    • [4. 先把安装包搞下来（以 3.1.0 为例）](#4. 先把安装包搞下来（以 3.1.0 为例）)
      • [方式 A：直接 wget（我就喜欢这种简单粗暴的）](#方式 A：直接 wget（我就喜欢这种简单粗暴的）)
      • [方式 B：浏览器下载再上传](#方式 B：浏览器下载再上传)
    • [5. 解压看看里头有啥](#5. 解压看看里头有啥)
    • [6. 搞定那些烦人的依赖（单机部署最容易翻车的地方）](#6. 搞定那些烦人的依赖（单机部署最容易翻车的地方）)
      • [6.1 先把该装的都装上](#6.1 先把该装的都装上)
    • [7. 改改配置文件 deploy.cfg](#7. 改改配置文件 deploy.cfg)
      • [7.1 模板 A（偷懒首选）：非安全模式 insecure](#7.1 模板 A（偷懒首选）：非安全模式 insecure)
      • [7.2 模板 B（生产环境推荐）：TLS 安全模式 tls](#7.2 模板 B（生产环境推荐）：TLS 安全模式 tls)
      • [7.3 原文件里哪些多余的段落](#7.3 原文件里哪些多余的段落)
    • [8. 一键安装，起飞！](#8. 一键安装，起飞！)
      • [8.1 给脚本加个执行权限](#8.1 给脚本加个执行权限)
      • [8.2 执行单机安装](#8.2 执行单机安装)
    • [9. 验货环节：服务、端口、连接、版本](#9. 验货环节：服务、端口、连接、版本)
      • [9.1 看看服务状态](#9.1 看看服务状态)
      • [9.2 检查端口监听](#9.2 检查端口监听)
      • [9.3 连上数据库看看版本](#9.3 连上数据库看看版本)
      • [9.4 最小化冒烟测试](#9.4 最小化冒烟测试)
    • [10. 踩坑实录：那些年我掉过的坑](#10. 踩坑实录：那些年我掉过的坑)
      • [10.1 坑 1：dpkg 安装半路夭折（缺 libgflags2.2 等依赖）](#10.1 坑 1：dpkg 安装半路夭折（缺 libgflags2.2 等依赖）)
      • [10.2 坑 2：装完了服务却在睡大觉（inactive）](#10.2 坑 2：装完了服务却在睡大觉（inactive）)
      • [10.3 坑 3：node_addr 填错，远程连不上](#10.3 坑 3：node_addr 填错，远程连不上)
      • [10.4 坑 4：在 bash 里敲 SQL](#10.4 坑 4：在 bash 里敲 SQL)
      • [10.5 坑 5：TLS 模式报 permission denied](#10.5 坑 5：TLS 模式报 permission denied)
      • [10.6 提醒：CPU 核数警告](#10.6 提醒：CPU 核数警告)
      • [10.7 坑 6：磁盘满了或者权限不对](#10.7 坑 6：磁盘满了或者权限不对)
    • [11. 进阶玩法：简单测测性能](#11. 进阶玩法：简单测测性能)
      • [11.1 核心特性体验：TLS 安全模式](#11.1 核心特性体验：TLS 安全模式)
      • [11.3 读写性能实测：搞个轻量级基线](#11.3 读写性能实测：搞个轻量级基线)
      • [11.4 读性能再挖深点：索引与执行计划](#11.4 读性能再挖深点：索引与执行计划)
      • [11.5 稳定性实测：重启大法](#11.5 稳定性实测：重启大法)
    • [12. 最后总结一下](#12. 最后总结一下)

1. 版本与部署路线怎么选

这次实战，咱们主要是在 Ubuntu 22.04 环境下，搞定 单机版 的命令行部署。

至于版本嘛，我强烈建议直接上 KWDB 3.1.0 。为啥？因为新版本在脚本易用性上做了不少优化，像配置确认、运维脚本这些，能省咱们不少心（具体的更新细节，感兴趣的可以去看看 release note：https://gitee.com/kwdb/kwdb/releases/tag/V3.1.0）。

2. 目标：这篇文章读完，能带走哪些"干货"？

等咱们这一通操作猛如虎之后，至少能搞定下面这 6 件事儿：

  1. 把系统环境和资源摸清楚（CPU、内存、磁盘这些底子）。
  2. 把那些磨人的依赖全装好（特别是 libprotobuf23、squashfs-tools 等容易漏的）。
  3. 让 KWDB 的部署脚本一次跑通（install --single）。
  4. 看着 systemd 服务乖乖变成 active 状态。
  5. 端口监听正常（默认的 26257 和 8080）。
  6. 最后，能顺顺利利连上数据库，敲一行 select version(); 看到回显。

3. 开干前的准备工作

3.1 摸底系统信息

先跑几个命令，看看咱们手里的机器到底是个什么配置：

bash 复制代码 
lsb_release -a
uname -a
lscpu | sed -n '1,20p'
free -h
df -hT
ip addr
timedatectl status

截图点位建议：

  • lsb_release -a 得确认是 Ubuntu 22.04.x，别搞错了。
  • free -h 内存最好有 4G 以上，8G 更稳当。
  • df -hT 磁盘留个 50G+ 吧，SSD 肯定比 HDD 香，ext4 文件系统也更靠谱点。

3.2 查查端口有没有被占

默认端口得先扫一眼，别到时候冲突了抓瞎：

bash 复制代码 
sudo ss -tuln | egrep '(:26257|:8080)\b' || true

要是看到有输出，那就尴尬了，说明端口被占了。要么在后面的 deploy.cfg 里换个端口，要么就把占用端口的服务给停了。

3.3 规划一下目录（墙裂推荐）

我个人习惯把"安装包"和"数据"分开放，这样以后排查问题或者清理的时候，心里更有数：

bash 复制代码 
sudo mkdir -p /app/kwdb/{soft,data}
sudo chown -R "$USER":"$USER" /app/kwdb
cd /app/kwdb/soft

4. 先把安装包搞下来（以 3.1.0 为例）

KWDB 在 Gitee Releases 上都有对应的包，直接去拿就行：

方式 A：直接 wget（我就喜欢这种简单粗暴的）

bash 复制代码 
cd /app/kwdb/soft

VERSION="3.1.0"
FILE="KWDB-${VERSION}-ubuntu22.04-intel-x86_64-debs.tar.gz"
URL="https://gitee.com/kwdb/kwdb/releases/download/V${VERSION}/${FILE}"

curl -I -L "$URL" | head -n 20
wget -O "$FILE" "$URL"

方式 B：浏览器下载再上传

如果你习惯在 Windows 上下载，也可以先下好，然后用 scp 或者 WinSCP 扔到服务器的 /app/kwdb/soft/ 目录下。

5. 解压看看里头有啥

bash 复制代码 
cd /app/kwdb/soft
tar -xzf "$FILE"

ls -al

解压完你会看到一个叫 kwdb_install 的目录，后面的操作咱们就都在这儿进行了。

6. 搞定那些烦人的依赖（单机部署最容易翻车的地方）

6.1 先把该装的都装上

别存侥幸心理，先把这些常用运行依赖一股脑装齐了：

bash 复制代码 
sudo apt update
sudo apt install -y ca-certificates curl wget tar \
  libprotobuf23 protobuf-compiler \
  libgflags2.2 \
  libssl-dev liblzma-dev libncurses-dev libatomic1 libstdc++6 \
  squashfs-tools

装完最好验一下：

bash 复制代码 
dpkg -s libprotobuf23 | grep -E '^Version'
dpkg -l | grep -E '^ii\s+libgflags' || true
protoc --version || true
dpkg -l | grep -E 'squashfs-tools|libprotobuf23' || true

多啰嗦两句：

  • 在 Ubuntu 22.04 上，最搞心态的就是 缺依赖导致 dpkg 报错。提前把这些装好，能省下大把排错的时间。
  • 特别是 squashfs-tools，这玩意儿经常被忽略，属于"隐形杀手"，没装的话安装阶段直接报错给你看。

7. 改改配置文件 deploy.cfg

进到解压出来的目录里：

bash 复制代码 
cd /app/kwdb/soft/kwdb_install
ls -al

用编辑器打开 deploy.cfg：

bash 复制代码 
nano deploy.cfg

这里面默认已经有不少内容了。对于单机安装，咱们通常只需要动两个地方：

  1. data_root：改成你刚才规划好的数据目录（比如 /app/kwdb/data/kaiwudb）。
  2. node_addr：改成你对外服务的 IP 地址，千万别开 [cluster]。

为了方便大家，我准备了两套模板，直接拿去用就行。

7.1 模板 A（偷懒首选）：非安全模式 insecure

如果你只是想快速跑通验证一下，或者嫌配证书麻烦，先用 insecure 模式凑合一下也行：

ini 复制代码 
[global]
secure_mode=insecure
management_user=kaiwudb
rest_port=8080
kaiwudb_port=26257
grpc_port=27257
data_root=/app/kwdb/data/kaiwudb

[local]
node_addr=你的公网地址

7.2 模板 B（生产环境推荐）：TLS 安全模式 tls

要是正儿八经用，或者想一步到位，建议直接上 TLS。node_addr 填客户端实际能连上的那个 IP。如果机器有内网和公网 IP，优先填对外能通的那个，省得后面证书报错或者路由不通。

ini 复制代码 
[global]
secure_mode=tls
management_user=kaiwudb
rest_port=8080
kaiwudb_port=26257
grpc_port=27257
data_root=/app/kwdb/data/kaiwudb

[local]
node_addr=你的公网IP

7.3 原文件里哪些多余的段落

如果 deploy.cfg 里还有 [cluster]、ssh_*、[additional] 这些乱七八糟的段落，单机部署的话，我建议统统删掉或者注释掉，只保留：

  • [global]
  • [local]

这样跑 ./deploy.sh install --single 的时候，脚本才不会傻乎乎地去检查什么远程节点。

8. 一键安装，起飞！

8.1 给脚本加个执行权限

bash 复制代码 
chmod +x ./deploy.sh

8.2 执行单机安装

bash 复制代码 
./deploy.sh install --single

安装跑完之后，别急着庆祝。我建议立刻刷新一下 systemd 并把服务拉起来，不然有时候会遇到"服务是有了，但状态还是 inactive"的尴尬情况：

bash 复制代码 
sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb

一般来说，安装结束后会自动搞定这几件事：

  • 创建好 kaiwudb 的 systemd 服务。
  • 生成几个运维用的脚本（像 kw-status.sh / kw-sql.sh 这些，看版本可能有差异）。
  • 在安装目录下生成日志文件夹（万一报错了，第一时间去看日志）。

9. 验货环节：服务、端口、连接、版本

9.1 看看服务状态

bash 复制代码 
sudo systemctl status kaiwudb --no-pager

要是看到状态是 inactive (dead)，别慌，先试着救一下：

bash 复制代码 
sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb
sudo systemctl status kaiwudb --no-pager

如果还是起不来，那就得祭出大杀器------看日志了：

bash 复制代码 
sudo journalctl -u kaiwudb -n 200 --no-pager

9.2 检查端口监听

bash 复制代码 
sudo ss -tulnp | egrep '(:26257|:8080)\b' || true

9.3 连上数据库看看版本

如果有生成的便捷脚本，直接用脚本最省事：

bash 复制代码 
ls -al | egrep 'kw-(sql|status)\.sh' || true
./kw-status.sh || true
./kw-sql.sh || true

要是没有 kw-sql.sh，那就用 kwbase 客户端硬连（注意 TLS 模式得带上证书目录）：

bash 复制代码 
sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257

进到客户端里头，敲个命令看看版本：

sql 复制代码 
select version();

如果你不加 sudo 报错 permission denied（读不到 /etc/kaiwudb/certs/*.key），那说明证书权限管得严，这是好事。想解决的话：

  • 快速法：像上面一样加 sudo。
  • 规范法：单独搞个"客户端证书目录"，把证书和私钥拷出来，把权限理顺了再用。

9.4 最小化冒烟测试

这一步咱们不整复杂的，就为了验证一句："这数据库确实能用"。

sql 复制代码 
create database if not exists demo;
create table if not exists demo.t_kv (
  id int primary key,
  v  varchar(64)
);

insert into demo.t_kv (id, v) values (1, 'hello-kwdb');
select * from demo.t_kv;

10. 踩坑实录：那些年我掉过的坑

为了让大家少走弯路，我把这次部署过程中遇到的、或者大家容易遇到的坑都整理出来了，按"现象 → 定位 → 解决 → 验证"的套路来复盘。

10.1 坑 1：dpkg 安装半路夭折（缺 libgflags2.2 等依赖）

现象

运行 ./deploy.sh install --single 的时候，脚本报错说缺依赖，然后直接退出了，或者 dpkg 报了一堆错。

如何定位

  • 看看终端输出里到底缺了啥。
  • 如果服务建了但起不来，journalctl -u kaiwudb 也能看出点端倪。

解决办法（Ubuntu 22.04 亲测有效）

bash 复制代码 
sudo apt update
sudo apt install -y libprotobuf23 squashfs-tools libgflags2.2
sudo apt --fix-broken install -y
sudo dpkg --configure -a

验证

bash 复制代码 
dpkg -l | grep -E 'libprotobuf23|squashfs-tools'
./deploy.sh install --single

10.2 坑 2：装完了服务却在睡大觉（inactive）

现象

脚本明明说安装成功了，结果一看 systemctl status kaiwudb 却是 inactive (dead)，端口也没动静。

如何定位

bash 复制代码 
sudo systemctl status kaiwudb --no-pager
sudo ss -tulnp | egrep '(:26257|:8080)\b' || true

解决办法

别忘了刷新和启用服务：

bash 复制代码 
sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb

验证

bash 复制代码 
sudo systemctl status kaiwudb --no-pager
sudo ss -tulnp | egrep '(:26257|:8080)\b' || true

10.3 坑 3：node_addr 填错，远程连不上

现象

服务跑得欢，端口也在监听，但死活从别的机器连不上，或者客户端握手失败。

如何定位

  • ip addr 看看本机 IP 到底是啥。
  • ss -tulnp | grep 26257 看看它到底监听在哪个 IP 上。

解决办法

  • 去 deploy.cfg 里把 node_addr 改成对外能通的那个 IP。
  • 检查防火墙是不是挡路了（测试环境可以先放开，生产环境按策略来）。

验证

  • 找台别的机器 telnet 一下端口试试（例如 telnet <ip> 26257 或 nc -vz <ip> 26257）。

10.4 坑 4：在 bash 里敲 SQL

现象

直接在 shell 里输 select version();，报错 syntax error near unexpected token '('。

解决办法

  • 别闹，先进 SQL shell 再说话：
bash 复制代码 
sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257

10.5 坑 5：TLS 模式报 permission denied

现象

运行 kwbase sql 的时候，提示读不到 /etc/kaiwudb/certs/*.key，权限不足。

解决办法

先用 sudo 跑通再说：

bash 复制代码 
sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257

10.6 提醒：CPU 核数警告

现象

安装或启动时提示：The number of CPU cores does not meet the requirement. KaiwuDB may running failed.

处理建议

  • 测试环境：只要能跑起来验收就行，别跑重负载任务。
  • 生产环境：还是老老实实给够资源吧，至少 4C8G 起步，不然以后 OOM 了有的哭。

10.7 坑 6：磁盘满了或者权限不对

现象

启动失败，日志里全是 permission denied 或者 no space left on device。

如何定位

bash 复制代码 
sudo journalctl -u kaiwudb -n 200 --no-pager
df -hT
ls -ld /app/kwdb/data /app/kwdb/data/kaiwudb || true

解决办法

  • 检查 data_root 目录权限对不对。
  • 看看磁盘是不是满了，赶紧清理或者挂个大点的盘。

验证

bash 复制代码 
sudo systemctl restart kaiwudb
sudo systemctl status kaiwudb --no-pager

11. 进阶玩法：简单测测性能

装都装好了，光看个版本号多没劲。咱们在"安装成功"的基础上，再做两个小实验，把"能跑通、能解释、能复现"这个闭环给扣上。

11.1 核心特性体验：TLS 安全模式

这次咱们配的是 secure_mode=tls，连接的时候也确实碰到了证书权限的问题。这其实是个好现象，说明安全模式不是摆设。它涉及证书生成、存放位置以及最小权限访问策略。

  • 服务端证书一般在：/etc/kaiwudb/certs
  • TLS 下连 SQL 的最短姿势：
bash 复制代码 
sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257

如果不加 sudo 就报权限错误，说明私钥权限管得严，这是对的。

11.3 读写性能实测：搞个轻量级基线

咱们不做复杂的压测，就做一个"讲道理"的基线测试：同一台机器、同一张表、同一批数据。资源有限，咱们就先测个 1 万行，别把机器跑崩了。

先建个表：

bash 复制代码 
cat <<'SQL' | sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257
create database if not exists bench;
create table if not exists bench.t_write (
  ts   timestamp,
  dev  varchar(32),
  v1   double precision,
  v2   double precision
);
SQL

写入测试（N=10000，可按需调整）：

bash 复制代码 
N=10000
(
  echo "begin;"
  for i in $(seq 1 "$N"); do
    echo "insert into bench.t_write values (now(), 'dev-01', $i, $i);"
  done
  echo "commit;"
) | time sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257

读查询测试（测测 count 和条件过滤）：

bash 复制代码 
cat <<'SQL' | time sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257
select count(*) from bench.t_write;
select count(*) from bench.t_write where dev='dev-01';
SQL

看这结果，在 N=10000 的数据量下：

  • 写入侧：事务提交秒级搞定，单条 INSERT 也是微秒级的，说明单机写入链路没毛病，响应挺快。
  • 读取侧：count(*) 毫秒级返回，结果也是对的，作为基线测试很合格。

11.4 读性能再挖深点：索引与执行计划

光测个 count(*) 没啥意思，咱们来点稍微高级的：看看加不加索引到底有多大区别。

创建索引：

bash 复制代码 
cat <<'SQL' | sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257
create index if not exists idx_t_write_dev on bench.t_write (dev);
SQL

建索引耗时百毫秒级别，符合预期。

对比查询耗时（多跑几次，去去水分）：

bash 复制代码 
for i in $(seq 1 5); do
  cat <<'SQL' | time sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257
select count(*) from bench.t_write where dev='dev-01';
SQL
done

5 次跑下来，耗时挺稳定。即便数据量不大，这种稳定性也能说明查询链路是靠谱的。

看看执行计划（Explain Analyze）：

bash 复制代码 
cat <<'SQL' | sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257
explain analyze select count(*) from bench.t_write where dev='dev-01';
SQL

explain analyze 能打出执行计划，这一步很关键。它让"快"变得有理有据------你能看到到底有没有走索引，扫描了多少行，每一步花了多久。以后要深入分析性能，这就得是常备技能了。

11.5 稳定性实测：重启大法

bash 复制代码 
sudo systemctl restart kaiwudb
sudo systemctl status kaiwudb --no-pager
sudo ss -tulnp | egrep '(:26257|:8080)\b' || true

重启完了再查查数据还在不在：

bash 复制代码 
cat <<'SQL' | sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257
select count(*) from bench.t_write;
SQL

如果数据还在，恭喜你，至少"安装 → 启动 → 写入 → 重启 → 数据持久化"这条路是通的。

12. 最后总结一下

  • 单机安装搞定：Ubuntu 22.04 + KWDB 3.1.0（TLS 模式），服务起了，端口通了。
  • 踩坑闭环：依赖缺失（libgflags2.2）知道咋补了；服务 inactive 知道咋救了；TLS 证书权限也知道咋绕过了。
  • 最小可用验证：建库、建表、写入、查询、重启，这一套流程全通。
  • 性能基线建立 ：1 万行数据量下的写入和查询基线有了，还通过索引和 explain analyze 把性能分析的架子搭起来了。
相关推荐
liwenzhuola1 小时前
解决 Ubuntu 上 Qt Creator 项目编译失败的问题
数据库·qt·ubuntu
AiGuoHou12 小时前
Debian/Ubuntu 各个版本一键更换国内镜像源
linux·ubuntu·国内源·debian·镜像源·换源
衡动科技2 小时前
Ubuntu 22.04/24.04 安装 ROS2 完整教程（Humble / Jazzy）
ubuntu·树莓派·ros2
蓝羽天空2 小时前
Ubuntu 24.04 安装 Docker
linux·ubuntu·docker
T0uken2 小时前
WSL：离线配置 Ubuntu 开发环境
linux·运维·ubuntu
�羡阳丶2 小时前
ubuntu22.04+5060显卡双系统安装，各种黑屏踩坑记录
linux·经验分享·ubuntu
b_xinjun11202 小时前
树莓派 Ubuntu 24.04.3 LTS 安装 OpenClaw 操作说明
linux·ubuntu·arcgis
暮秋4742 小时前
ubuntu部署阿里通义千问模型
运维·ubuntu·大模型
维度攻城狮2 小时前
Docker-Ubuntu安装并启动Chrome浏览器
chrome·ubuntu·docker·安装
热门推荐
012026年3月AI领域大事件：DeepSeek引领开源风暴02GitHub 镜像站点03Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南04围棋-html版本05小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）06班级宠物园部署指南07UV安装并设置国内源08OpenClaw 使用和管理 MCP 完全指南09【计算机一级WPSoffice】小黑课堂题库软件下载安装教程（2026年3月最新版）10“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）