KWDB 3.1.0 版本在运维脚本和配置管理上做了优化，但单机部署时仍可能因环境适配或依赖缺失导致问题。本文基于 Ubuntu 22.04 环境，从实战角度拆解 KaiwuDB 3.1.0 的单机部署全流程，涵盖环境核查、依赖安装、配置文件调整及常见问题排查，并通过服务验证与性能测试完成验收。
1. 版本与部署路线选择
本次实战针对 Ubuntu 22.04 环境下的 单机版 命令行部署。建议直接使用 KWDB 3.1.0，新版本在脚本易用性上有显著改进，能减少配置确认和运维脚本的复杂度。具体更新细节可参考官方 Release Note。
2. 部署目标
完成本流程后，你将能够：
- 确认系统资源（CPU、内存、磁盘）满足要求。
- 安装必要的运行依赖（如 libprotobuf23、squashfs-tools 等）。
- 成功执行单机安装脚本
install --single。 - 确保 systemd 服务状态为 active。
- 验证默认端口（26257 和 8080）正常监听。
- 通过 SQL 客户端连接数据库并查询版本。
3. 准备工作
3.1 系统信息核查
先确认当前机器配置是否符合要求：
lsb_release -a
uname -a
lscpu | sed -n '1,20p'
free -h
df -hT
timedatectl status
重点确认：
- 系统是 Ubuntu 22.04.x。
- 内存至少 4G，推荐 8G。
- 磁盘空间 50G+，建议使用 SSD 和 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. 获取安装包
访问 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：浏览器下载上传
若习惯本地操作，可下载后通过 scp 或 WinSCP 上传至服务器 /app/kwdb/soft/ 目录。
5. 解压文件
cd /app/kwdb/soft
tar -xzf "$FILE"
ls -al
解压后将看到 kwdb_install 目录，后续操作均在此进行。
6. 安装依赖
单机部署最容易在依赖环节翻车，建议提前装齐常用库：
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
nano deploy.cfg
单机部署主要修改两处：
data_root：指向规划好的数据目录（如/app/kwdb/data/kaiwudb）。node_addr：填写对外服务的 IP，不要开启[cluster]配置。
7.1 非安全模式（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 TLS 安全模式（tls）
生产环境推荐使用，一步到位：
[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
如有内网/公网双 IP，优先填对外可通的地址，避免路由问题。
7.3 清理多余段落
若 deploy.cfg 中存在 [cluster]、ssh_*、[additional] 等段落，单机部署建议注释或删除，只保留 [global] 和 [local]，防止脚本误检远程节点。
8. 执行安装
8.1 添加执行权限
chmod +x ./deploy.sh
8.2 运行安装脚本
./deploy.sh install --single
安装完成后，建议立即刷新 systemd 并启动服务，避免状态异常：
sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb
通常安装会自动创建 systemd 服务、生成运维脚本（如 kw-status.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
若无脚本，使用 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，说明证书权限受限，属正常现象。可通过加 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 dpkg 安装中断（缺依赖）
现象：脚本运行时报错缺依赖，dpkg 失败。
定位：查看终端输出或 journalctl -u kaiwudb。
解决：
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 服务 inactive
现象：安装成功但服务未启动，端口无监听。 解决：刷新并启用服务。
sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb
10.3 node_addr 填错
现象：服务正常但远程无法连接。
解决：修改 deploy.cfg 中的 node_addr 为对外通联 IP，检查防火墙策略。
10.4 直接在 bash 敲 SQL
现象：Shell 输入 select version(); 报错语法错误。
解决：先进入 SQL Shell 再执行命令。
10.5 TLS 权限不足
现象：连接时报读不到证书文件。
解决：使用 sudo 运行客户端，或调整证书目录权限。
10.6 CPU 核数警告
现象：提示 CPU 核心数不满足要求。 处理：测试环境可忽略，生产环境建议至少 4C8G。
10.7 磁盘满或权限错
现象：启动失败，日志报 permission denied 或 no space left。
解决：检查 data_root 权限及磁盘剩余空间。
11. 进阶玩法：性能基线
11.1 TLS 安全模式体验
配置 secure_mode=tls 后，连接涉及证书生成与最小权限策略。服务端证书通常在 /etc/kaiwudb/certs，连接时需指定 --certs-dir。
11.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
(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
结果分析：写入事务秒级提交，单条微秒级；读取 count(*) 毫秒级返回，基线合格。
11.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 查看执行计划，确认是否走索引及扫描行数。
11.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
若数据仍在，说明安装、启动、写入、重启链路完整。
12. 总结
- 单机安装完成：Ubuntu 22.04 + KWDB 3.1.0（TLS 模式），服务正常，端口连通。
- 问题闭环：依赖缺失、服务 inactive、TLS 权限等问题均有解决方案。
- 验证通过：建库、建表、写入、查询、重启全通。
- 性能基线：1 万行数据量下写入读取表现稳定，索引与执行计划分析框架已搭建。
