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

方式 B：浏览器下载上传

在本地下载后，通过 scp 或 WinSCP 上传至服务器 /app/kwdb/soft/ 目录。

5. 解压文件

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

特别注意 squashfs-tools，未安装会导致安装阶段报错。

7. 配置文件修改

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

cd /app/kwdb/soft/kwdb_install
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

删除 [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

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 -n200 --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 直接在 Shell 敲 SQL 报错

现象：Shell 提示 syntax error。 解决：先进入 SQL Shell：

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

10.5 TLS 模式权限不足

现象：读取证书报 permission denied。 解决：使用 sudo 运行命令，或调整证书目录权限。

10.6 CPU 核数警告

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

10.7 磁盘满或权限错误

现象：启动失败，日志显示 no space left on device。 解决：清理磁盘空间，检查 data_root 目录权限。

11. 性能测试

11.1 TLS 安全模式体验

服务端证书位于 /etc/kaiwudb/certs。连接时需指定 --certs-dir。

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;") | sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257

读查询测试：

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

对比查询耗时及执行计划：

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

12. 总结

• 单机安装：Ubuntu 22.04 + KWDB 3.1.0（TLS 模式），服务正常启动。
• 问题排查：覆盖依赖缺失、服务状态异常、TLS 权限等常见场景。
• 功能验证：建库、建表、写入、查询、重启全流程通过。
• 性能基线：建立 1 万行数据量下的读写基线，支持索引与执行计划分析。