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

方式二：手动上传

若使用 Windows 本地下载，可通过 scp 或 WinSCP 将文件上传至 /app/kwdb/soft/。

解压与初始化

tar -xzf "$FILE"
ls -al

解压后将进入 kwdb_install 目录进行后续操作。

安装依赖

单机部署最容易因依赖缺失失败，请提前安装：

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，缺少该包会导致安装阶段报错。

配置文件调整

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

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

单机部署主要关注两项配置：

1. data_root：修改为规划的数据目录（如 /app/kwdb/data/kaiwudb）。
2. node_addr：填写对外服务的 IP 地址，不要开启 [cluster] 相关配置。

模板 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=你的公网地址

模板 B：TLS 安全模式（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] 等段落，单机部署时建议注释或删除，避免脚本误检远程节点。

执行安装

赋予执行权限

chmod +x ./deploy.sh

运行安装脚本

./deploy.sh install --single

安装完成后，建议立即刷新 systemd 并启动服务：

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

通常会自动创建 kaiwudb 服务、生成运维脚本（如 kw-status.sh）及日志目录。

服务验证

检查服务状态

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

检查端口监听

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

连接数据库

优先使用生成的便捷脚本：

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 运行，或将证书复制到用户目录并调整权限。

冒烟测试

验证基本读写能力：

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;

常见问题排查

依赖缺失导致安装中断

现象：脚本报错缺依赖或 dpkg 异常。

解决：

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

服务未启动

现象：安装成功但服务状态为 inactive。

解决：

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

远程连接失败

现象：端口监听正常但外部无法连接。

排查：

• 检查 deploy.cfg 中的 node_addr 是否为对外可达 IP。
• 确认防火墙策略是否放行 26257 端口。
• 使用 telnet <ip> 26257 测试连通性。

SQL 语法错误

现象：直接在 Shell 输入 SQL 报错。

解决：必须进入 SQL 交互模式后再执行语句。

证书权限不足

现象：TLS 模式下访问证书目录报 permission denied。

解决：使用 sudo 运行客户端，或规范配置证书目录权限。

资源警告

现象：启动时提示 CPU 核数不足。

建议：测试环境可忽略，生产环境建议至少 4C8G。

磁盘空间或权限问题

现象：日志显示 no space left on device 或 permission denied。

解决：

df -hT
ls -ld /app/kwdb/data /app/kwdb/data/kaiwudb

清理空间或修正目录权限后重启服务。

性能基线测试

写入性能测试

创建测试表并写入 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

索引优化

创建索引并对比查询耗时：

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 查看执行计划：

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

稳定性验证

重启服务并检查数据持久化：

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

总结

• 部署完成：Ubuntu 22.04 + KWDB 3.1.0（TLS 模式），服务正常，端口通畅。
• 问题闭环：依赖缺失、服务未启动、证书权限等问题均有对应解决方案。
• 功能验证：建库、建表、写入、查询、重启流程全部通过。
• 性能基线：建立了 1 万行数据量的读写基准，并通过索引和执行计划分析验证了查询效率。