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

方式 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

进入解压目录编辑 deploy.cfg：

cd /app/kwdb/soft/kwdb_install
nano deploy.cfg

单机部署通常只需修改 data_root 和 node_addr，删除 [cluster]、ssh_* 等段落，保留 [global] 和 [local]。

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

8. 执行安装

8.1 添加执行权限

chmod +x ./deploy.sh

8.2 运行脚本

./deploy.sh install --single

安装完成后刷新 systemd 并启用服务：

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

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

执行 SQL：

select version();

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 安装失败（缺依赖）

现象：脚本报错缺依赖或退出。 解决：

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

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

现象：语法错误。 解决：先进入 SQL shell。

10.5 TLS 模式权限不足

现象：读不到证书文件。 解决：使用 sudo 运行命令，或调整证书目录权限。

10.6 CPU 核数警告

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

10.7 磁盘满或权限不对

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

11. 性能测试

11.1 TLS 安全模式体验

服务端证书位于 /etc/kaiwudb/certs。连接时需注意私钥权限策略。

11.2 读写性能基线

创建测试表：

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 );

写入测试（N=10000）：

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

11.3 索引与执行计划

创建索引：

create index if not exists idx_t_write_dev on bench.t_write (dev);

对比查询耗时：

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

查看执行计划：

explain analyze select count(*) from bench.t_write where dev='dev-01';

11.4 稳定性测试

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

验证数据持久化：

select count(*) from bench.t_write;

12. 总结

• 单机安装：Ubuntu 22.04 + KWDB 3.1.0（TLS 模式），服务正常，端口通畅。
• 故障排查：覆盖依赖缺失、服务 inactive、节点地址及权限问题。
• 最小可用验证：建库、建表、写入、查询、重启流程全通。
• 性能基线：建立 1 万行数据量下的读写基线，并通过索引与执行计划分析优化查询。