KWDB 作为一款易用性不断优化的数据库产品，其 3.1.0 版本在运维脚本、配置管理等方面的升级为部署带来了便利，但新手在单机部署过程中仍易因环境适配、依赖缺失、配置不当等问题踩坑。为帮助开发者快速落地 KWDB 单机环境，本文以 Ubuntu 22.04 为基础环境，从实战角度出发，完整拆解 KWDB 3.1.0 单机部署的全流程：不仅明确版本选型依据和部署目标，还细化了环境核查、安装包获取、依赖配置、部署脚本执行等关键操作，针对性解决部署中的高频问题，并通过服务验证、性能基线测试完成最小化验收，最终实现 “安装即能用、问题有解法、效果可验证” 的部署目标，为 KWDB 入门者提供清晰、可复现的实操指引。
文章目录
-
- 1. 版本与部署路线怎么选
- 2. 目标：这篇文章读完，能带走哪些“干货”？
- 3. 开干前的准备工作
-
- 3.1 摸底系统信息
- 3.2 查查端口有没有被占
- 3.3 规划一下目录（墙裂推荐）
- 4. 先把安装包搞下来（以 3.1.0 为例）
-
- 方式 A：直接 wget（我就喜欢这种简单粗暴的）
- 方式 B：浏览器下载再上传
- 5. 解压看看里头有啥
- 6. 搞定那些烦人的依赖（单机部署最容易翻车的地方）
-
- 6.1 先把该装的都装上
- 7. 改改配置文件 deploy.cfg
-
- 7.1 模板 A（偷懒首选）：非安全模式 insecure
- 7.2 模板 B（生产环境推荐）：TLS 安全模式 tls
- 7.3 原文件里哪些多余的段落
- 8. 一键安装，起飞！
-
- 8.1 给脚本加个执行权限
- 8.2 执行单机安装
- 9. 验货环节：服务、端口、连接、版本
-
- 9.1 看看服务状态
- 9.2 检查端口监听
- 9.3 连上数据库看看版本
- 9.4 最小化冒烟测试
- 10. 踩坑实录：那些年我掉过的坑
-
- 10.1 坑 1：dpkg 安装半路夭折（缺 libgflags2.2 等依赖）
- 10.2 坑 2：装完了服务却在睡大觉（inactive）
- 10.3 坑 3：node_addr 填错，远程连不上
- 10.4 坑 4：在 bash 里敲 SQL
- 10.5 坑 5：TLS 模式报 permission denied
- 10.6 提醒：CPU 核数警告
- 10.7 坑 6：磁盘满了或者权限不对
- 11. 进阶玩法：简单测测性能
-
- 11.1 核心特性体验：TLS 安全模式
- 11.3 读写性能实测：搞个轻量级基线
- 11.4 读性能再挖深点：索引与执行计划
- 11.5 稳定性实测：重启大法
- 12. 最后总结一下
1. 版本与部署路线怎么选
这次实战，咱们主要是在 Ubuntu 22.04 环境下，搞定 单机版 的命令行部署。
至于版本嘛，我强烈建议直接上 KWDB 3.1.0。为啥？因为新版本在脚本易用性上做了不少优化，像配置确认、运维脚本这些，能省咱们不少心（具体的更新细节，感兴趣的可以去看看 release note：https://gitee.com/kwdb/kwdb/releases/tag/V3.1.0）。
2. 目标：这篇文章读完，能带走哪些“干货”？
等咱们这一通操作猛如虎之后，至少能搞定下面这 6 件事儿：
3. 开干前的准备工作
3.1 摸底系统信息
先跑几个命令，看看咱们手里的机器到底是个什么配置：
lsb_release -a
uname -a
lscpu | sed -n '1,20p'
free -h
df -hT
ip 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 规划一下目录（墙裂推荐）
我个人习惯把“安装包”和“数据”分开放，这样以后排查问题或者清理的时候，心里更有数：
sudo mkdir -p /app/kwdb/{soft,data}
sudo chown -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 -n 20
wget -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 先把该装的都装上
别存侥幸心理，先把这些常用运行依赖一股脑装齐了：
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，这玩意儿经常被忽略，属于“隐形杀手”，没装的话安装阶段直接报错给你看。
7. 改改配置文件 deploy.cfg
进到解压出来的目录里：
cd /app/kwdb/soft/kwdb_install
ls -al
用编辑器打开 deploy.cfg：
nano deploy.cfg
这里面默认已经有不少内容了。对于单机安装，咱们通常只需要动两个地方：
为了方便大家，我准备了两套模板，直接拿去用就行。
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 -n 200 –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 最小化冒烟测试
这一步咱们不整复杂的，就为了验证一句：“这数据库确实能用”。
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;
10. 踩坑实录：那些年我掉过的坑
为了让大家少走弯路，我把这次部署过程中遇到的、或者大家容易遇到的坑都整理出来了，按“现象 → 定位 → 解决 → 验证”的套路来复盘。
10.1 坑 1：dpkg 安装半路夭折（缺 libgflags2.2 等依赖）
现象 运行 ./deploy.sh install –single 的时候，脚本报错说缺依赖，然后直接退出了，或者 dpkg 报了一堆错。
如何定位
- 看看终端输出里到底缺了啥。
- 如果服务建了但起不来，journalctl -u kaiwudb 也能看出点端倪。
解决办法（Ubuntu 22.04 亲测有效）
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
10.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' || true
10.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 -n 200 –no-pager
df -hT
ls -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;"
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(*) 毫秒级返回，结果也是对的，作为基线测试很合格。
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
建索引耗时百毫秒级别，符合预期。
对比查询耗时（多跑几次，去去水分）：
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
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 把性能分析的架子搭起来了。
