KaiwuDB 3.1.0 在 Ubuntu 22.04 部署实战：TLS 配置与性能基线

• Releases 总览：https://gitee.com/kwdb/kwdb/releases
• 3.1.0 版本：https://gitee.com/kwdb/kwdb/releases/tag/V3.1.0

方式 A：直接 wget

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：浏览器下载上传

若习惯本地操作，可下载后通过 scp 或 WinSCP 上传至服务器 /app/kwdb/soft/ 目录。

5. 解压文件

cd /app/kwdb/soft
tar -xzf "$FILE"
ls -al

解压后将看到 kwdb_install 目录，后续操作均在此进行。

6. 安装依赖

单机部署最容易在依赖环节翻车，建议提前装齐常用库：

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

安装后验证关键依赖：

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

进入解压目录：

cd /app/kwdb/soft/kwdb_install
ls -al
nano deploy.cfg

单机部署主要修改两处：

1. data_root：指向规划好的数据目录（如 /app/kwdb/data/kaiwudb）。
2. node_addr：填写对外服务的 IP，不要开启 [cluster] 配置。

7.1 非安全模式（insecure）

仅用于快速验证，无需证书：

[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 TLS 安全模式（tls）

生产环境推荐使用，一步到位：

[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

如有内网/公网双 IP，优先填对外可通的地址，避免路由问题。

7.3 清理多余段落

若 deploy.cfg 中存在 [cluster]、ssh_*、[additional] 等段落，单机部署建议注释或删除，只保留 [global] 和 [local]，防止脚本误检远程节点。

8. 执行安装

8.1 添加执行权限

chmod +x ./deploy.sh

8.2 运行安装脚本

./deploy.sh install --single

安装完成后，建议立即刷新 systemd 并启动服务，避免状态异常：

sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb

通常安装会自动创建 systemd 服务、生成运维脚本（如 kw-status.sh）及日志文件夹。

9. 验货环节

9.1 检查服务状态

sudo systemctl status kaiwudb --no-pager

若显示 inactive (dead)，尝试以下修复：

sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb
sudo systemctl status kaiwudb --no-pager

仍无法启动则查看日志：

sudo journalctl -u kaiwudb -n 200 --no-pager

9.2 检查端口监听

sudo ss -tulnp | egrep '(:26257|:8080)\b' || true

9.3 连接数据库

若有便捷脚本可直接使用：

ls -al | egrep 'kw-(sql|status)\.sh' || true
./kw-status.sh || true
./kw-sql.sh || true

若无脚本，使用 kwbase 客户端直连（TLS 模式需指定证书目录）：

sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257

进入客户端后查询版本：

select version();

若不加 sudo 报 permission denied，说明证书权限受限，属正常现象。可通过加 sudo 或规范配置客户端证书目录解决。

9.4 冒烟测试

验证基本功能可用性：

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 dpkg 安装中断（缺依赖）

现象：脚本运行时报错缺依赖，dpkg 失败。 定位：查看终端输出或 journalctl -u kaiwudb。 解决：

sudo apt update
sudo apt install -y libprotobuf23 squashfs-tools libgflags2.2
sudo apt --fix-broken install -y
sudo dpkg --configure -a

验证：

dpkg -l | grep -E 'libprotobuf23|squashfs-tools'
./deploy.sh install --single

10.2 服务 inactive

现象：安装成功但服务未启动，端口无监听。 解决：刷新并启用服务。

sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb

10.3 node_addr 填错

现象：服务正常但远程无法连接。 解决：修改 deploy.cfg 中的 node_addr 为对外通联 IP，检查防火墙策略。

10.4 直接在 bash 敲 SQL

现象：Shell 输入 select version(); 报错语法错误。 解决：先进入 SQL Shell 再执行命令。

10.5 TLS 权限不足

现象：连接时报读不到证书文件。 解决：使用 sudo 运行客户端，或调整证书目录权限。

10.6 CPU 核数警告

现象：提示 CPU 核心数不满足要求。 处理：测试环境可忽略，生产环境建议至少 4C8G。

10.7 磁盘满或权限错

现象：启动失败，日志报 permission denied 或 no space left。 解决：检查 data_root 权限及磁盘剩余空间。

11. 进阶玩法：性能基线

11.1 TLS 安全模式体验

配置 secure_mode=tls 后，连接涉及证书生成与最小权限策略。服务端证书通常在 /etc/kaiwudb/certs，连接时需指定 --certs-dir。

11.2 读写性能实测

建立轻量级基线，写入 1 万行数据：

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
(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

读取测试：

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

结果分析：写入事务秒级提交，单条微秒级；读取 count(*) 毫秒级返回，基线合格。

11.3 索引与执行计划

创建索引对比查询效率：

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

多次跑测查询耗时，观察稳定性。使用 explain analyze 查看执行计划，确认是否走索引及扫描行数。

11.4 稳定性测试

重启服务验证数据持久化：

sudo systemctl restart kaiwudb
sudo systemctl status kaiwudb --no-pager
sudo ss -tulnp | egrep '(:26257|:8080)\b' || true
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 模式），服务正常，端口连通。
• 问题闭环：依赖缺失、服务 inactive、TLS 权限等问题均有解决方案。
• 验证通过：建库、建表、写入、查询、重启全通。
• 性能基线：1 万行数据量下写入读取表现稳定，索引与执行计划分析框架已搭建。