KWDB 3.1.0 在 Ubuntu 22.04 环境下的单机部署全流程指南。涵盖系统环境核查、依赖安装、配置文件修改（支持 insecure 与 TLS 模式）、脚本执行及服务验证。详细记录了常见部署问题如依赖缺失、服务状态异常、端口占用及权限错误的解决方案，并包含基于 1 万行数据的读写性能基线测试与索引优化分析，确保安装即用且可验证。
KWDB 3.1.0 版本在运维脚本和配置管理等方面进行了优化，为单机部署带来了便利。本文以 Ubuntu 22.04 为基础环境，从实战角度出发，完整拆解 KWDB 3.1.0 单机部署的全流程，包括环境核查、依赖配置、脚本执行及服务验证，并通过性能基线测试完成验收。
本次实战基于 Ubuntu 22.04 环境，采用 单机版 命令行部署方式。建议直接使用 KWDB 3.1.0 版本，新版本在脚本易用性上做了优化（详见 Gitee Release）。
完成以下操作后，应达成以下目标：
install --single。lsb_release -a
uname -a
lscpu | sed -n '1,20p'
free -h
df -hT
ip addr
timedatectl status
sudo ss -tuln | egrep '(:26257|:8080)\b' || true
若端口被占用，需在 deploy.cfg 中修改端口或停止占用服务。
建议将安装包和数据分开存放：
sudo mkdir -p /app/kwdb/{soft,data}
sudo chown -R "$USER":"$USER" /app/kwdb
cd /app/kwdb/soft
前往 Gitee Releases 下载对应包：https://gitee.com/kwdb/kwdb/releases
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}"
wget -O "$FILE" "$URL"
在本地下载后，通过 scp 或 WinSCP 上传至服务器 /app/kwdb/soft/ 目录。
tar -xzf "$FILE"
ls -al
解压后将看到 kwdb_install 目录，后续操作在此进行。
单机部署最容易因依赖缺失导致失败，建议提前安装：
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
特别注意 squashfs-tools，未安装会导致安装阶段报错。
进入解压目录编辑 deploy.cfg：
cd /app/kwdb/soft/kwdb_install
nano deploy.cfg
主要修改两项：
data_root：改为规划的数据目录（如 /app/kwdb/data/kaiwudb）。node_addr：改为对外服务的 IP 地址，删除 [cluster] 相关配置。适用于快速验证：
[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=你的公网地址
生产环境推荐：
[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_*、[additional] 等多余段落，仅保留 [global] 和 [local]。
chmod +x ./deploy.sh
./deploy.sh install --single
安装完成后刷新 systemd 并启用服务：
sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb
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
sudo ss -tulnp | egrep '(:26257|:8080)\b' || true
使用生成的便捷脚本或客户端连接：
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
执行 SQL 查看版本：
select version();
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;
现象：脚本运行时报错缺依赖。 解决：
sudo apt update
sudo apt install -y libprotobuf23 squashfs-tools libgflags2.2
sudo apt --fix-broken install -y
sudo dpkg --configure -a
现象：安装成功但服务未启动。 解决：
sudo systemctl daemon-reload
sudo systemctl enable --now kaiwudb
现象：端口监听但外部无法连接。
解决：修改 deploy.cfg 中的 node_addr 为对外可通 IP，并检查防火墙策略。
现象：Shell 提示 syntax error。 解决：先进入 SQL Shell：
sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257
现象：读取证书报 permission denied。 解决：使用 sudo 运行命令，或调整证书目录权限。
现象：提示 CPU 核心数不满足要求。 建议：测试环境可忽略，生产环境建议至少 4C8G。
现象：启动失败，日志显示 no space left on device。
解决：清理磁盘空间，检查 data_root 目录权限。
服务端证书位于 /etc/kaiwudb/certs。连接时需指定 --certs-dir。
创建测试表：
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 );
写入测试（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;") | sudo /usr/local/kaiwudb/bin/kwbase sql --certs-dir=/etc/kaiwudb/certs --host=127.0.0.1:26257
读查询测试：
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;
select count(*) from bench.t_write where dev='dev-01';
SQL
创建索引：
create index if not exists idx_t_write_dev on bench.t_write (dev);
对比查询耗时及执行计划：
explain analyze select count(*) from bench.t_write where dev='dev-01';
重启服务并验证数据持久化：
sudo systemctl restart kaiwudb
sudo systemctl status kaiwudb --no-pager
sudo ss -tulnp | egrep '(:26257|:8080)\b' || true
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online
将JSON字符串修饰为友好的可读格式。 在线工具，JSON美化和格式化在线工具，online