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

方式 B：浏览器下载 Windows 用户可下载后通过 scp 或 WinSCP 上传至 /app/kwdb/soft/。

三、解压与依赖安装

解压后进入 kwdb_install 目录：

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

1. 安装运行依赖

这是最容易翻车的环节，务必提前装齐：

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 下缺 squashfs-tools 常导致安装阶段报错，属于隐形杀手。

四、配置文件修改

编辑 deploy.cfg：

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，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_* 等段落，单机模式下建议注释或删除，避免脚本误检远程节点。

五、执行安装

1. 赋予权限并安装

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

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

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

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

六、服务验证

1. 检查状态

sudo systemctl status kaiwudb --no-pager

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

sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb
sudo journalctl -u kaiwudb -n 200 --no-pager

2. 检查端口

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

3. 连接数据库

使用生成的脚本或 kwbase 客户端：

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

若无脚本，直接连接：

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

执行 SQL 验证版本：

select version();

若提示 permission denied，说明证书权限严格，加 sudo 或使用规范的用户证书目录即可。

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;

七、常见问题复盘

1. 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

现象：安装成功但服务未启动。 解决：刷新并启用服务。

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

3. node_addr 填错

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

4. 直接在 Bash 敲 SQL

现象：报错 syntax error。 解决：必须进入 SQL Shell 后再执行命令。

5. TLS 权限问题

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

6. 资源不足警告

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

7. 磁盘满或权限错误

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

八、性能基线测试

1. 写入测试

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

2. 查询测试

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

3. 索引优化

创建索引并对比查询计划：

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 select count(*) from bench.t_write where dev='dev-01';

4. 稳定性测试

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

sudo systemctl restart kaiwudb
sudo systemctl status kaiwudb --no-pager
sudo ss -tulnp | grep -E '(: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 证书权限等常见问题。通过建库、建表、写入、查询及重启测试，验证了数据持久化的可靠性。同时建立了 1 万行数据量下的读写性能基线，并结合 explain analyze 分析了索引效果，为后续生产环境落地提供了参考依据。