KWDB 3.1.0 在 Ubuntu 22.04 部署实战：TLS 配置、踩坑复盘与轻量压测
KWDB 作为一款易用性不断优化的数据库产品，其 3.1.0 版本在运维脚本、配置管理等方面的升级为部署带来了便利，但新手在单机部署过程中仍易因环境适配、依赖缺失、配置不当等问题踩坑。为帮助开发者快速落地 KWDB 单机环境，本文以 Ubuntu 22.04 为基础环境，从实战角度出发，完整拆解 KWDB 3.1.0 单机部署的全流程：不仅明确版本选型依据和部署目标，还细化了环境核查、安装包获取、依赖配置、部署脚本执行等关键操作，针对性解决部署中的高频问题，并通过服务验证、性能基线测试完成最小化验收，最终实现 “安装即能用、问题有解法、效果可验证” 的部署目标，为 KWDB 入门者提供清晰、可复现的实操指引。
文章目录
1. 版本与部署路线怎么选
这次实战，咱们主要是在 Ubuntu 22.04 环境下，搞定 单机版 的命令行部署。
至于版本嘛，我强烈建议直接上 KWDB 3.1.0。为啥？因为新版本在脚本易用性上做了不少优化，像配置确认、运维脚本这些，能省咱们不少心（具体的更新细节，感兴趣的可以去看看 release note：https://gitee.com/kwdb/kwdb/releases/tag/V3.1.0）。
2. 目标：这篇文章读完，能带走哪些“干货”？
等咱们这一通操作猛如虎之后，至少能搞定下面这 6 件事儿：
- 把系统环境和资源摸清楚（CPU、内存、磁盘这些底子）。
- 把那些磨人的依赖全装好（特别是 libprotobuf23、squashfs-tools 等容易漏的）。
- 让 KWDB 的部署脚本一次跑通（install --single）。
- 看着 systemd 服务乖乖变成 active 状态。
- 端口监听正常（默认的 26257 和 8080）。
- 最后，能顺顺利利连上数据库，敲一行
select version();看到回显。
3. 开干前的准备工作
3.1 摸底系统信息
先跑几个命令，看看咱们手里的机器到底是个什么配置：
lsb_release -auname-a lscpu |sed-n'1,20p'free-hdf-hTip addr timedatectl status 截图点位建议：
lsb_release -a得确认是 Ubuntu 22.04.x，别搞错了。free -h内存最好有 4G 以上，8G 更稳当。df -hT磁盘留个 50G+ 吧，SSD 肯定比 HDD 香，ext4 文件系统也更靠谱点。
3.2 查查端口有没有被占
默认端口得先扫一眼，别到时候冲突了抓瞎：
sudo ss -tuln|egrep'(:26257|:8080)\b'||true
要是看到有输出，那就尴尬了，说明端口被占了。要么在后面的 deploy.cfg 里换个端口，要么就把占用端口的服务给停了。
3.3 规划一下目录（墙裂推荐）
我个人习惯把“安装包”和“数据”分开放，这样以后排查问题或者清理的时候，心里更有数：
sudomkdir-p /app/kwdb/{soft,data}sudochown-R"$USER":"$USER" /app/kwdb cd /app/kwdb/soft 4. 先把安装包搞下来（以 3.1.0 为例）
KWDB 在 Gitee Releases 上都有对应的包，直接去拿就行：
- Releases 总览页：https://gitee.com/kwdb/kwdb/releases
- 3.1.0 版本页：https://gitee.com/kwdb/kwdb/releases/tag/V3.1.0
方式 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-n20wget-O"$FILE""$URL"
方式 B：浏览器下载再上传
如果你习惯在 Windows 上下载，也可以先下好，然后用 scp 或者 WinSCP 扔到服务器的 /app/kwdb/soft/ 目录下。
5. 解压看看里头有啥
cd /app/kwdb/soft tar-xzf"$FILE"ls-al解压完你会看到一个叫 kwdb_install 的目录，后面的操作咱们就都在这儿进行了。
6. 搞定那些烦人的依赖（单机部署最容易翻车的地方）
6.1 先把该装的都装上
别存侥幸心理，先把这些常用运行依赖一股脑装齐了：
sudoapt update sudoaptinstall-y ca-certificates curlwgettar\ 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用编辑器打开 deploy.cfg：
nano deploy.cfg 这里面默认已经有不少内容了。对于单机安装，咱们通常只需要动两个地方：
data_root：改成你刚才规划好的数据目录（比如/app/kwdb/data/kaiwudb）。node_addr：改成你对外服务的 IP 地址，千万别开[cluster]。
为了方便大家，我准备了两套模板，直接拿去用就行。
7.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=你的公网地址 7.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 
7.3 原文件里哪些多余的段落
如果 deploy.cfg 里还有 [cluster]、ssh_*、[additional] 这些乱七八糟的段落，单机部署的话，我建议统统删掉或者注释掉，只保留：
[global][local]
这样跑 ./deploy.sh install --single 的时候，脚本才不会傻乎乎地去检查什么远程节点。
8. 一键安装，起飞！
8.1 给脚本加个执行权限
chmod +x ./deploy.sh 8.2 执行单机安装
./deploy.sh install--single安装跑完之后，别急着庆祝。我建议立刻刷新一下 systemd 并把服务拉起来，不然有时候会遇到“服务是有了，但状态还是 inactive”的尴尬情况：
sudo systemctl daemon-reload sudo systemctl enable--now kaiwudb 
一般来说，安装结束后会自动搞定这几件事：
- 创建好
kaiwudb的 systemd 服务。 - 生成几个运维用的脚本（像
kw-status.sh/kw-sql.sh这些，看版本可能有差异）。 - 在安装目录下生成日志文件夹（万一报错了，第一时间去看日志）。
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 -n200 --no-pager 9.2 检查端口监听
sudo ss -tulnp|egrep'(:26257|:8080)\b'||true
9.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。 - 规范法：单独搞个“客户端证书目录”，把证书和私钥拷出来，把权限理顺了再用。
9.4 最小化冒烟测试
这一步咱们不整复杂的，就为了验证一句：“这数据库确实能用”。
createdatabaseifnotexists demo;createtableifnotexists demo.t_kv ( id intprimarykey, v varchar(64));insertinto demo.t_kv (id, v)values(1,'hello-kwdb');select*from demo.t_kv;10. 踩坑实录：那些年我掉过的坑
为了让大家少走弯路，我把这次部署过程中遇到的、或者大家容易遇到的坑都整理出来了，按“现象 → 定位 → 解决 → 验证”的套路来复盘。
10.1 坑 1：dpkg 安装半路夭折（缺 libgflags2.2 等依赖）
现象
运行 ./deploy.sh install --single 的时候，脚本报错说缺依赖，然后直接退出了，或者 dpkg 报了一堆错。
如何定位
- 看看终端输出里到底缺了啥。
- 如果服务建了但起不来，
journalctl -u kaiwudb也能看出点端倪。
解决办法（Ubuntu 22.04 亲测有效）
sudoapt update sudoaptinstall-y libprotobuf23 squashfs-tools libgflags2.2 sudoapt --fix-broken install-ysudo dpkg --configure-a验证
dpkg -l|grep-E'libprotobuf23|squashfs-tools' ./deploy.sh install--single10.2 坑 2：装完了服务却在睡大觉（inactive）
现象
脚本明明说安装成功了，结果一看 systemctl status kaiwudb 却是 inactive (dead)，端口也没动静。
如何定位
sudo systemctl status kaiwudb --no-pager sudo ss -tulnp|egrep'(:26257|:8080)\b'||true解决办法
别忘了刷新和启用服务：
sudo systemctl daemon-reload sudo systemctl enable--now kaiwudb 验证
sudo systemctl status kaiwudb --no-pager sudo ss -tulnp|egrep'(:26257|:8080)\b'||true10.3 坑 3：node_addr 填错，远程连不上
现象
服务跑得欢，端口也在监听，但死活从别的机器连不上，或者客户端握手失败。
如何定位
ip addr看看本机 IP 到底是啥。ss -tulnp | grep 26257看看它到底监听在哪个 IP 上。
解决办法
- 去
deploy.cfg里把node_addr改成对外能通的那个 IP。 - 检查防火墙是不是挡路了（测试环境可以先放开，生产环境按策略来）。
验证
- 找台别的机器 telnet 一下端口试试（例如
telnet <ip> 26257或nc -vz <ip> 26257）。
10.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 10.5 坑 5：TLS 模式报 permission denied
现象
运行 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 10.6 提醒：CPU 核数警告
现象
安装或启动时提示：The number of CPU cores does not meet the requirement. KaiwuDB may running failed.
处理建议
- 测试环境：只要能跑起来验收就行，别跑重负载任务。
- 生产环境：还是老老实实给够资源吧，至少 4C8G 起步，不然以后 OOM 了有的哭。
10.7 坑 6：磁盘满了或者权限不对
现象
启动失败，日志里全是 permission denied 或者 no space left on device。
如何定位
sudo journalctl -u kaiwudb -n200 --no-pager df-hTls-ld /app/kwdb/data /app/kwdb/data/kaiwudb ||true解决办法
- 检查
data_root目录权限对不对。 - 看看磁盘是不是满了，赶紧清理或者挂个大点的盘。
验证
sudo systemctl restart kaiwudb sudo systemctl status kaiwudb --no-pager 11. 进阶玩法：简单测测性能
装都装好了，光看个版本号多没劲。咱们在“安装成功”的基础上，再做两个小实验，把“能跑通、能解释、能复现”这个闭环给扣上。
11.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 就报权限错误，说明私钥权限管得严，这是对的。
11.3 读写性能实测：搞个轻量级基线
咱们不做复杂的压测，就做一个“讲道理”的基线测试：同一台机器、同一张表、同一批数据。资源有限，咱们就先测个 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;"foriin$(seq1"$N");doecho"insert into bench.t_write values (now(), 'dev-01', $i, $i);"doneecho"commit;")|timesudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257 读查询测试（测测 count 和条件过滤）：
cat<<'SQL'|timesudo /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(*)毫秒级返回，结果也是对的，作为基线测试很合格。
11.4 读性能再挖深点：索引与执行计划
光测个 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建索引耗时百毫秒级别，符合预期。
对比查询耗时（多跑几次，去去水分）：
foriin$(seq15);docat<<'SQL'|timesudo /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'; SQLdone
5 次跑下来，耗时挺稳定。即便数据量不大，这种稳定性也能说明查询链路是靠谱的。
看看执行计划（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 能打出执行计划，这一步很关键。它让“快”变得有理有据——你能看到到底有没有走索引，扫描了多少行，每一步花了多久。以后要深入分析性能，这就得是常备技能了。
11.5 稳定性实测：重启大法
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
如果数据还在，恭喜你，至少“安装 → 启动 → 写入 → 重启 → 数据持久化”这条路是通的。
12. 最后总结一下
- 单机安装搞定：Ubuntu 22.04 + KWDB 3.1.0（TLS 模式），服务起了，端口通了。
- 踩坑闭环：依赖缺失（libgflags2.2）知道咋补了；服务 inactive 知道咋救了；TLS 证书权限也知道咋绕过了。
- 最小可用验证：建库、建表、写入、查询、重启，这一套流程全通。
- 性能基线建立：1 万行数据量下的写入和查询基线有了，还通过索引和
explain analyze把性能分析的架子搭起来了。
