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

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

Windows 用户可下载后通过 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 模板 A：非安全模式 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 模板 B：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 -n 200 --no-pager

9.2 检查端口监听

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

9.3 连接数据库

使用便捷脚本或客户端硬连（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 报错。 解决：

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

现象：安装成功但服务未启动。 解决：务必执行 daemon-reload 和 enable --now。

10.3 node_addr 填错导致远程连不上

现象：本地正常，远程无法连接。 解决：检查 deploy.cfg 中的 node_addr 是否为对外 IP，并确认防火墙策略。

10.4 直接在 bash 敲 SQL 报错

现象：shell 提示 syntax error。 解决：先进入 SQL shell 再执行命令。

10.5 TLS 模式权限不足

现象：读不到 /etc/kaiwudb/certs/*.key。 解决：使用 sudo 运行客户端，或规范配置证书目录权限。

10.6 CPU 核数警告

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

10.7 磁盘满或权限错误

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

11. 性能基线测试

11.1 读写性能实测

创建测试表：

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

读取测试：

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

11.2 索引与执行计划

创建索引：

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.3 稳定性测试

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

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

查询数据确认未丢失：

select count(*) from bench.t_write;