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

方式 A：直接 wget

cd /app/kwdb/soft
VERSION="3.1.0"
FILE="KWDB-${VERSION}-ubuntu22.04-intel-x86_64-debs.tar.gz"
URL="https://gitee.com/kwdb/kwdb/releases/download/V${VERSION}/${FILE}"

curl -I -L "$URL" | head -n 20
wget -O "$FILE" "$URL"

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

如果你习惯在 Windows 上下载，也可以先下好，然后用 scp 或者 WinSCP 扔到服务器的 /app/kwdb/soft/ 目录下。

4. 解压与依赖配置

4.1 解压查看

cd /app/kwdb/soft
tar -xzf "$FILE"
ls -al

解压完你会看到一个叫 kwdb_install 的目录，后面的操作咱们就都在这儿进行了。

4.2 安装依赖

别存侥幸心理，先把这些常用运行依赖一股脑装齐了：

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，这玩意儿经常被忽略，属于'隐形杀手'，没装的话安装阶段直接报错给你看。

5. 修改配置文件 deploy.cfg

进到解压出来的目录里：

cd /app/kwdb/soft/kwdb_install
ls -al

用编辑器打开 deploy.cfg：

nano deploy.cfg

这里面默认已经有不少内容了。对于单机安装，通常只需要动两个地方：

1. data_root：改成你刚才规划好的数据目录（比如 /app/kwdb/data/kaiwudb）。
2. node_addr：改成你对外服务的 IP 地址，千万别开 [cluster]。

为了方便大家，我准备了两套模板，直接拿去用就行。

5.1 模板 A：非安全模式 insecure

如果你只是想快速跑通验证一下，或者嫌配证书麻烦，先用 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=你的公网地址

5.2 模板 B：TLS 安全模式 tls

要是正儿八经用，或者想一步到位，建议直接上 TLS。node_addr 填客户端实际能连上的那个 IP。如果机器有内网和公网 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

5.3 清理多余段落

如果 deploy.cfg 里还有 [cluster]、ssh_*、[additional] 这些乱七八糟的段落，单机部署的话，我建议统统删掉或者注释掉，只保留：

• [global]
• [local]

这样跑 ./deploy.sh install --single 的时候，脚本才不会傻乎乎地去检查什么远程节点。

6. 一键安装

6.1 添加执行权限

chmod +x ./deploy.sh

6.2 执行单机安装

./deploy.sh install --single

安装跑完之后，别急着庆祝。我建议立刻刷新一下 systemd 并把服务拉起来，不然有时候会遇到'服务是有了，但状态还是 inactive'的尴尬情况：

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

一般来说，安装结束后会自动搞定这几件事：

• 创建好 kaiwudb 的 systemd 服务。
• 生成几个运维用的脚本（像 kw-status.sh / kw-sql.sh 这些，看版本可能有差异）。
• 在安装目录下生成日志文件夹（万一报错了，第一时间去看日志）。

7. 验货环节

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

7.2 检查端口监听

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

7.3 连接数据库

如果有生成的便捷脚本，直接用脚本最省事：

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

要是没有 kw-sql.sh，那就用 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（读不到 /etc/kaiwudb/certs/*.key），那说明证书权限管得严，这是好事。想解决的话：

• 快速法：像上面一样加 sudo。
• 规范法：单独搞个'客户端证书目录'，把证书和私钥拷出来，把权限理顺了再用。

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

8. 踩坑实录

为了让大家少走弯路，我把这次部署过程中遇到的、或者大家容易遇到的坑都整理出来了，按'现象 → 定位 → 解决 → 验证'的套路来复盘。

8.1 坑 1：dpkg 安装半路夭折

现象：运行 ./deploy.sh install --single 的时候，脚本报错说缺依赖，然后直接退出，或者 dpkg 报了一堆错。

解决办法：

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

验证：

dpkg -l | grep -E 'libprotobuf23|squashfs-tools'
./deploy.sh install --single

8.2 坑 2：服务 inactive

现象：脚本明明说安装成功了，结果一看 systemctl status kaiwudb 却是 inactive (dead)，端口也没动静。

解决办法：别忘了刷新和启用服务：

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

8.3 坑 3：node_addr 填错

现象：服务跑得欢，端口也在监听，但死活从别的机器连不上，或者客户端握手失败。

解决办法：

• 去 deploy.cfg 里把 node_addr 改成对外能通的那个 IP。
• 检查防火墙是不是挡路了（测试环境可以先放开，生产环境按策略来）。

验证：找台别的机器 telnet 一下端口试试（例如 telnet <ip> 26257 或 nc -vz <ip> 26257）。

8.4 坑 4：在 bash 里敲 SQL

现象：直接在 shell 里输 select version();，报错 syntax error near unexpected token '('。

解决办法：别闹，先进 SQL shell 再说话：

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

8.5 坑 5：TLS 模式权限不足

现象：运行 kwbase sql 的时候，提示读不到 /etc/kaiwudb/certs/*.key，权限不足。

解决办法：先用 sudo 跑通再说：

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

8.6 提醒：CPU 核数警告

现象：安装或启动时提示：The number of CPU cores does not meet the requirement. KaiwuDB may running failed.

处理建议：

• 测试环境：只要能跑起来验收就行，别跑重负载任务。
• 生产环境：还是老老实实给够资源吧，至少 4C8G 起步，不然以后 OOM 了有的哭。

8.7 坑 6：磁盘满了或者权限不对

现象：启动失败，日志里全是 permission denied 或者 no space left on device。

解决办法：

• 检查 data_root 目录权限对不对。
• 看看磁盘是不是满了，赶紧清理或者挂个大点的盘。

验证：

sudo systemctl restart kaiwudb
sudo systemctl status kaiwudb --no-pager

9. 进阶玩法：简单测测性能

装都装好了，光看个版本号多没劲。咱们在'安装成功'的基础上，再做两个小实验，把'能跑通、能解释、能复现'这个闭环给扣上。

9.1 核心特性体验：TLS 安全模式

这次咱们配的是 secure_mode=tls，连接的时候也确实碰到了证书权限的问题。这其实是个好现象，说明安全模式不是摆设。它涉及证书生成、存放位置以及最小权限访问策略。

• 服务端证书一般在：/etc/kaiwudb/certs
• TLS 下连 SQL 的最短姿势：

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

如果不加 sudo 就报权限错误，说明私钥权限管得严，这是对的。

9.2 读写性能实测

咱们不做复杂的压测，就做一个'讲道理'的基线测试：同一台机器、同一张表、同一批数据。资源有限，咱们就先测个 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

读查询测试（测测 count 和条件过滤）：

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

看这结果，在 N=10000 的数据量下：

• 写入侧：事务提交秒级搞定，单条 INSERT 也是微秒级的，说明单机写入链路没毛病，响应挺快。
• 读取侧：count(*) 毫秒级返回，结果也是对的，作为基线测试很合格。

9.3 索引与执行计划

光测个 count(*) 没啥意思，咱们来点稍微高级的：看看加不加索引到底有多大区别。

创建索引：

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

建索引耗时百毫秒级别，符合预期。

对比查询耗时（多跑几次，去去水分）：

for i in $(seq 1 5); do
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 where dev='dev-01';
SQL
done

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

explain analyze 能打出执行计划，这一步很关键。它让'快'变得有理有据——你能看到到底有没有走索引，扫描了多少行，每一步花了多久。以后要深入分析性能，这就得是常备技能了。

9.4 稳定性实测：重启大法

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

如果数据还在，恭喜你，至少'安装 → 启动 → 写入 → 重启 → 数据持久化'这条路是通的。

10. 总结

• 单机安装搞定：Ubuntu 22.04 + KaiwuDB 3.1.0（TLS 模式），服务起了，端口通了。
• 踩坑闭环：依赖缺失（libgflags2.2）知道咋补了；服务 inactive 知道咋救了；TLS 证书权限也知道咋绕过了。
• 最小可用验证：建库、建表、写入、查询、重启，这一套流程全通。
• 性能基线建立：1 万行数据量下的写入和查询基线有了，还通过索引和 explain analyze 把性能分析的架子搭起来了。