介绍 KaiwuDB 3.1.0 版本在 Ubuntu 22.04 环境下的单机部署全流程。内容包括系统环境核查、依赖包安装、配置文件（deploy.cfg）修改（支持 insecure 与 TLS 模式）、一键安装脚本执行及服务验证。针对常见部署问题如依赖缺失、服务状态 inactive、端口占用及证书权限等提供解决方案，并包含基础读写性能测试与索引优化分析，帮助开发者快速搭建可用数据库环境。
本次实战基于 Ubuntu 22.04 环境，完成 单机版 KaiwuDB 的命令行部署。建议直接使用 KWDB 3.1.0 版本，新版本在脚本易用性和配置管理上有所优化。
完成以下操作后，应能实现：
运行命令确认环境配置：
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 文件系统更佳。默认端口需先扫描，避免冲突：
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 下载对应包：
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"
Windows 用户可下载后通过 scp 或 WinSCP 上传至服务器 /app/kwdb/soft/。
cd /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
注意：Ubuntu 22.04 上缺依赖会导致 dpkg 报错，特别是 squashfs-tools 常被忽略。
进入解压目录：
cd /app/kwdb/soft/kwdb_install
ls -al
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 -n 200 --no-pager
sudo ss -tulnp | egrep '(:26257|:8080)\b' || true
使用便捷脚本或客户端硬连（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 或调整证书目录权限。
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;
现象：脚本报错缺依赖，dpkg 报错。 解决：
sudo apt update
sudo apt install -y libprotobuf23 squashfs-tools libgflags2.2
sudo apt --fix-broken install -y
sudo dpkg --configure -a
现象：安装成功但服务未启动。
解决：务必执行 daemon-reload 和 enable --now。
现象：本地正常，远程无法连接。
解决：检查 deploy.cfg 中的 node_addr 是否为对外 IP，并确认防火墙策略。
现象：shell 提示 syntax error。 解决：先进入 SQL shell 再执行命令。
现象：读不到 /etc/kaiwudb/certs/*.key。
解决：使用 sudo 运行客户端，或规范配置证书目录权限。
现象：提示 CPU 核心数不满足要求。 处理：测试环境可忽略，生产环境建议至少 4C8G。
现象：启动失败，日志报 no space left on device。
解决：清理磁盘空间，检查 data_root 目录权限。
创建测试表：
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
读取测试：
select count(*) from bench.t_write;
select count(*) from bench.t_write where dev='dev-01';
创建索引：
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
查询数据确认未丢失：
select count(*) from bench.t_write;
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 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