拿到一款新数据库，最让人头疼的往往不是功能够不够强，而是第一步"装起来"就遇到各种问题------环境怎么配？单机体验和生产部署有什么区别？Docker 怎么跑？
别担心，这篇文章为你准备了一份 KaiwuDB 社区版全场景安装指南。从环境准备，到三种模式（单机、集群、容器）的安装步骤，再到验证连接和常见问题排查，全都帮你梳理清楚了。无论你是快速体验尝鲜，还是为正式项目做准备，跟着这篇文章走，就能顺利跑通第一个 KaiwuDB 实例。
接下来，我们从环境准备开始，一步步拆解三种场景下的具体操作吧！
01 环境准备
1.1 硬件要求
1.2 依赖安装
• Ubuntu/Debian 系
# 并安装依赖
sudo apt update && sudo apt install -y libgflags2.2 libprotoc32t64 libssl3t64 zlib1g liblz4-1 liblzma5 libkrb5-3 libncurses6
• CentOS/RHEL 系
# 安装依赖
sudo yum install -y gflags openssl-libs lz4 zlib xz-libs protobuf krb5-libs ncurses-libs
1.3 安装包获取
下载地址：
• KaiwuDB 官网下载中心
• KaiwuDB 社区版发布仓库：gitee.com/kwdb/kwdb/r…
选择对应系统版本的安装包：
• 二进制包：KWDB-版本-系统版本-架构-debs/rpms/docker.tar.gz（推荐）
• 容器镜像：kwdb/kwdb:版本（Docker 场景）
02 两种安装部署方式
方式一：二进制包一键部署
（推荐，单机/集群通用）
2.1 解压安装包
# 创建安装目录并解压
mkdir -p /soft && cd /soft
# 替换为实际下载的包名
tar -xvf KWDB-2.2.0-ubuntu22.04-x86_64-debs.tar.gz
cd kwdb_install/
2.2 配置
修改 deploy.cfg 配置文件，自定义端口、存储路径等：
[global]
secure_mode=tls # 是否开启加密传输，可选择 tls/tlcp/insecure
management_user=kaiwudb # 创建的系统用户名称
rest_port=8080 # http 服务端口
kaiwudb_port=26257 # kwdb 服务端口
brpc_port=27257 # brpc 远程调用端口
data_root=/var/lib/kaiwudb # kwdb 数据存放路径
[local]
node_addr=127.0.0.1 # 本机IP
# 若部署集群模式需要进行以下配置，若安装单机版需删除以下配置
[cluster]
node_addr=127.0.0.2 # 集群其他节点IP，多个节点使用逗号分隔
ssh_port=22 # 集群其他节点 SSH 连接端口
ssh_user=songxing # 集群其他节点 SSH 连接用户
部署集群时除本机外的其他节点均使用 SSH 进行连接后进行部署，请为其他节点配置相同的 SSH 端口和用户以及本机到其他节点的 SSH 免密。
2.3 执行安装
# 单机安装
./deploy.sh install --single
# 单副本集群安装
./deploy.sh install --single-replica
# 三副本集群安装
./deploy.sh install --multi-replica
2.4 单机启动/集群初始化
# 单机模式安装后可以使用系统服务或脚本启动数据库
systemctl daemon-reload && systemctl start kaiwudb
./deploy.sh start
# 单副本及三副本集群安装完成后，需要执行初始化命令完成整个集群初始化
./deploy.sh cluster --init
• 后续数据库运维均可使用 systemd 对数据库服务进行管理
• 初始化集群执行完成后,会启动所有节点中的 KaiwuDB 数据库并完成整个集群初始化
方式二：Docker 容器部署
（快速体验/测试环境）
2.1 前提条件
已安装 Docker 及 Docker Compose（v2+），未安装可以参考官方文档中有关安装教程：docs.docker.com/engine/inst…
2.2 快速启动（单节点非安全模式）
# 拉取镜像（3.1.0最新版）
docker pull kwdb/kwdb:3.1.0
# 启动容器
docker run -d \
--name kaiwudb-container \
-p 26257:26257 \
-p 8080:8080 \
-p 27257:27257 \
-w /kaiwudb/bin \
-v /data/kaiwudb:/kaiwudb/deploy/kaiwudb-container \
kwdb/kwdb:3.1.0 \
/kaiwudb/bin/kwbase start-single-node --insecure --listen-addr=0.0.0.0:26257 --http-addr=0.0.0.0:8080 --brpc-addr=0.0.0.0:27257 --store=/kaiwudb/deploy/kaiwudb-container
2.3 使用 Docker Compose 进行快速部署体验（单节点非安装模式快速启动）
创建 docker-compose.yml：
services:
kaiwudb:
image: kwdb/kwdb:3.1.0
container_name: kaiwudb-container
working_dir: /kaiwudb/bin
ports:
- 26257:26257
- 8080:8080
- 27257:27257
volumes:
- /data/kaiwudb:/kaiwudb/deploy/kaiwudb-container
restart: unless-stopped
ulimits:
memlock: -1
environment:
- TZ=Asia/Shanghai
entrypoint: ["/kaiwudb/bin/kwbase", "start-single-node", "--insecure", "--listen-addr=0.0.0.0:26257", "--http-addr=0.0.0.0:8080", "--brpc-addr=0.0.0.0:27257", "--store=/kaiwudb/deploy/kaiwudb-container"]
启动：
docker compose up -d
03 启动与验证（核心步骤）
3.1 启动服务
• 二进制包/源码部署
# 启动服务
sudo systemctl start kaiwudb
# 设置开机自启
sudo systemctl enable kaiwudb
• Docker 部署
# 启动容器
docker start kaiwudb
# 查看容器状态
docker ps | grep kaiwudb
3.2 验证服务状态
# 查看服务状态（安装包方式）
sudo systemctl status kaiwudb
# 查看容器日志（Docker）
docker logs kaiwudb
• 正常状态：输出 active (running)，日志无报错。
3.3 连接数据库
• 使用安装包部署
# 执行以下命令可快速进入 kwdb sql 命令行
kw-sql
• Docker 部署
# 进入容器并连接
docker exec -it kaiwudb /kaiwudb/bin/kwbase sql --insecure --host=127.0.0.1:26257
• 连接成功标识：进入 kwbase> 命令行提示符，可执行 SQL 操作。
3.4 基础测试（验证功能）
-- 1. 创建测试数据库
CREATE DATABASE test_db;
USE test_db;
-- 2. 创建时序表（包含时间戳与设备ID，多模核心特性）
CREATE TABLE device_metrics (
time TIMESTAMP NOT NULL,
device_id STRING NOT NULL,
temperature FLOAT,
humidity FLOAT,
PRIMARY KEY (time, device_id)
);
-- 3. 插入测试数据
INSERT INTO device_metrics VALUES
('2026-03-16 10:00:00', 'device_001', 25.3, 45.2),
('2026-03-16 10:05:00', 'device_001', 25.5, 44.8);
-- 4. 查询数据
SELECT * FROM device_metrics WHERE device_id = 'device_001';
执行无报错，返回数据即部署成功。
04 常见问题与解决方案
05 总结
最后，简单为大家总结一下三种场景怎么选：
• 如果你想快速上手体验，不用纠结，直接选 Docker 部署，一行命令就能跑起来，最适合拿来测试和学习。
• 如果你准备单机上线生产，二进制包一键部署更稳妥，配置灵活，稳定性也更有保障。
• 如果你需要搭建高可用集群，建议部署 3 个节点以上，再配上防火墙和安全策略，业务连续性才真正稳得住。
以上就是本期 KaiwuDB 社区版安装部署实战分享，如果你在实际操作中遇到什么问题，欢迎在评论区留言交流。更多 KaiwuDB 技术干货，请持续关注我们的公众号，下期见！
