KaiwuDB 3.1.0 在 Ubuntu 22.04 的单机部署与 TLS 配置实践

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

tar -xzf "$FILE"
cd kwdb_install
ls -al

依赖处理

单机部署最容易翻车的地方在于依赖缺失。务必提前安装以下常用运行库：

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 文件，单机部署通常只需关注 data_root 和 node_addr 两项，无需开启 [cluster] 相关配置。

nano deploy.cfg

模板 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 模式，node_addr 填写对外可通的 IP 地址。

[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_* 等段落，建议注释或删除，以免脚本误检远程节点。

执行安装

赋予脚本执行权限并运行单机安装命令：

chmod +x ./deploy.sh
./deploy.sh install --single

安装结束后，建议立即刷新 systemd 并启用服务，防止出现服务状态异常：

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

服务验证

状态检查

sudo systemctl status kaiwudb --no-pager

若显示 inactive (dead)，尝试重启服务并查看日志：

sudo systemctl restart kaiwudb
sudo journalctl -u kaiwudb -n200 --no-pager

端口监听

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

连接测试

使用生成的快捷脚本或 kwbase 客户端连接数据库：

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

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

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

进入 SQL 交互界面后执行：

select version();

若遇到 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;

常见问题排查

1. 依赖缺失导致 dpkg 报错

现象：安装脚本中途退出或 dpkg 报缺依赖。

解决：手动补全依赖并修复损坏的安装包。

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

2. 服务状态为 inactive

现象：安装提示成功，但 systemctl status 显示未激活。

解决：重新加载配置并启动服务。

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

3. node_addr 配置错误

现象：本地正常，远程无法连接。

解决：检查本机 IP (ip addr) 与 deploy.cfg 中的 node_addr 是否一致，并确认防火墙策略允许访问。

4. 直接在 Bash 敲 SQL

现象：终端直接输入 select version(); 报错语法错误。

解决：必须先进入 SQL Shell 再执行语句。

5. TLS 模式权限不足

现象：连接时报错读不到 /etc/kaiwudb/certs/*.key。

解决：使用 sudo 执行客户端命令，或调整证书目录权限。

6. 资源警告

现象：提示 CPU 核数不满足要求。

建议：测试环境可忽略，生产环境建议至少 4C8G 起步，避免 OOM。

7. 磁盘空间或权限问题

现象：启动失败，日志提示 no space left on device 或 permission denied。

解决：清理磁盘空间，检查 data_root 目录权限归属。

性能基准测试

读写性能

建立一张测试表并写入 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）：

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

查看执行计划分析：

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 环境下 KaiwuDB 3.1.0 的单机安装与 TLS 配置。通过环境预检、依赖补全、配置修正及故障排查，确保了服务的稳定运行。同时建立了基础的读写性能基线，验证了数据持久化能力。对于生产环境，建议严格遵循 TLS 安全模式，并根据实际负载调整资源配置。