kwcli：开源一个 KaiwuDB 社区版的 CLI 工具

工欲善其事，必先利其器。玩数据库，先从一把趁手的 CLI 开始。☕

最近我在 GitHub 上开源了一个叫 kwcli 的小工具，专门给 KWDB（KaiwuDB 社区版）生态做命令行管理。从一键拉起 Playground 学习环境，到单机版 KWDB 的装、启、停、配，再到内置的智能电表 SampleDB 场景体验，全部浓缩成几条命令。这篇文章，我就从第三方视角，带大家完整走一遍 kwcli 的使用流程，顺便聊聊 KWDB 社区版这个国产时序数据库的新锐选手。

01. 为什么做 kwcli？先说说背景

2024 年 8 月，浪潮 KaiwuDB 宣布开源，社区版命名为 KWDB，一个月后又捐赠给了开放原子开源基金会，成为基金会旗下首个分布式多模数据库项目。这在国内数据库开源圈里，算得上是一件大事。

KWDB 的定位很清晰：面向 AIoT 场景，支持同一实例里同时跑时序库和关系库，做到真正的多模融合。benchANT 全球时序数据库性能测s试榜单上，KWDB 商业版 KaiwuDB 曾以 1.37ms 的平均查询延迟刷新纪录，写入吞吐领先原榜单 1.5~1.8 倍，查询吞吐更是达到了 3.9~4.9 倍。

但笔者在体验社区版的过程中发现，新手想快速跑起来，门槛还是有的，能不能给 KWDB 也配一个"一把梭"的 CLI 工具？

答案是肯定的。kwcli 采用 Go 编写，基于组件化架构设计，所有功能按需加载、独立扩展。目前已在 GitHub 开源，Apache 2.0 协议，欢迎 Star & PR。

https://github.com/shawn0915/kwcli

已同步更新到 AtomGit | GitCode。

https://gitcode.com/mydb/kwcli

关于作者：严少安, PostgreSQL ACE, KWDB MVP，持有 KWCA, KWCP, KWCE 等认证。
公众号「少安事务所」，由 严少安 主笔，专注于数据 & AI 领域技术传播。

02. kwcli 安装

kwcli 的安装门槛很低，核心依赖就两个：Go 1.21+（仅编译时需要）和 Docker（Playground 和 KWDB Docker 部署需要）。

2.1 直接下载二进制文件（推荐）

直接下载二进制包，赋予可执行权限，即可使用。

wget https://github.com/shawn0915/kwcli/releases/download/v0.1.0/kwcli-linux-amd64
chmod +x kwcli-linux-amd64

2.2 编译源码

# 克隆仓库，可切换为 AtomGit（国内加速）
git clone https://github.com/shawn0915/kwcli.git
cd kwcli

# 一键构建，自动注入编译时间和 Git Commit Hash
make

# 安装到系统 PATH（需 sudo）
make install

# 或仅安装到用户目录
make install-local

2.3 验证安装

[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli -v
kwcli version 0.1.0-ShawnYan (Git Hash: 8e54bc2, Built at 2026-05-02 01:09:53 +0800)

装好之后，第一件事建议配置代码源。kwcli 默认优先走 AtomGit，国内访问速度快；如果你想切换回 GitHub，也只是一条命令的事：

# 查看当前默认代码源
kwcli source

# 切换到 GitHub
kwcli source github

# 切回 AtomGit
kwcli source atomgit

03. 一键启动 Playground：打开浏览器就能学

KWDB Playground 是社区推出的轻量级交互式课程平台，核心价值一句话：打开浏览器，即刻开始学习。过去想体验 KWDB，得先过"环境关"，现在用 kwcli 秒级搞定。

3.1 启动 Playground

# 首次会自动下载镜像并启动
kwcli playground start

# 指定版本安装
kwcli playground install -v v1.1.0

# 升级 Playground（代码源和镜像源可分别指定）
kwcli playground upgrade --source atomgit --registry auto

启动完成后，打开浏览器访问 http://localhost:3006，就能看到 Playground 的 Web 界面。里面内置了系列课程，从时序库建表、数据写入，到跨模查询，边学边练，零门槛上手。

3.2 Playground 生命周期管理

# 查看运行状态
kwcli playground status

# 查看日志
kwcli playground logs

# 重启
kwcli playground restart

# 停止服务
kwcli playground stop

# 查看已安装版本
kwcli playground versions

# 彻底卸载（加 --remove-files 删除所有数据）
kwcli playground uninstall --remove-files

笔者实测，在一台 8C16G 的 Linux 虚机上，从执行 start 到浏览器可访问，全程不到 30 秒。Docker 镜像默认走阿里云镜像仓库，国内下载速度很稳，这点必须给个好评 🌻。

04. 单机版 KWDB 部署：Docker 方式一键搞定

Playground 适合学习，但如果你想在本地搭一个真正的 KWDB 实例做开发测s试，kwcli 也提供了 kwdb 组件。

4.1 安装与启动

# 安装 KWDB（自动选择 Docker 方式）
kwcli kwdb install

# 启动服务
kwcli kwdb start

# 查看状态
kwcli kwdb status

4.2 配置管理

# 查看当前配置
kwcli kwdb config show

# 交互式编辑配置
kwcli kwdb config edit

# 查看配置文件路径
kwcli kwdb config path

示例：

[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli kwdb config edit

=== KWDB Configuration Wizard ===
Press Enter to use the default value shown in brackets.
SQL Port [26257]:
HTTP Port [8080]:
Data Directory [/home/shawnyan/.kwcli/components/kwdb/data]:
Log Directory [/home/shawnyan/.kwcli/components/kwdb/logs]:
Use insecure mode (disable authentication) [Y/n]:
SQL Listen Address [0.0.0.0:26257]:
HTTP Listen Address [0.0.0.0:8080]:
Configuration saved. Restart KWDB for changes to take effect.
[shawnyan@DESKTOP-SHAWN kwcli]$
[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli kwdb config path
/home/shawnyan/.kwcli/components/kwdb/config.yaml
[shawnyan@DESKTOP-SHAWN kwcli]$

4.3 日常运维

# 查看日志
kwcli kwdb logs

# 重启服务
kwcli kwdb restart

# 停止服务
kwcli kwdb stop

这里要提一下，kwcli 的组件都是隔离安装在 ~/.kwcli/components/ 目录下的，不影响系统环境，多版本可以共存。这种设计和 TiUP 的组件仓库思路很像，对 DBA 来说很友好，不用担心"装乱了"的问题。

~/.kwcli/
├── components/          # 组件安装目录
│   ├── playground/
│   │   └── versions/    # 多版本共存
│   └── kwdb/            # KWDB 安装目录
├── data/                # 运行时数据
└── config.yaml          # 全局配置（代码源等）

05. SQL 连接：像用 mysql 客户端一样用 kwcli

kwcli 内置了 SQL 连接功能，不需要额外安装 kwbase CLI 或者其他客户端。

# 交互式连接（默认连接 root 用户）
kwcli sql

# 执行单条 SQL
kwcli sql -e "SELECT version();"

# 指定用户和数据库
kwcli sql -u admin -d device_info

连接进去之后，你就可以体验 KWDB 的多模能力了。这里贴一段官方文档里的典型操作，感受一下时序库和关系库在同一个实例里协同工作的体验：

-- 创建关系数据库，存设备静态信息
CREATE DATABASE device_info;
USE device_info;

CREATE TABLE devices (
    device_id INT PRIMARY KEY,
    device_name VARCHAR NOT NULL,
    location VARCHAR,
    status VARCHAR DEFAULT 'active'
);

INSERT INTO devices VALUES
    (101, '传感器A', '机房1', 'active'),
    (102, '传感器B', '机房2', 'active');

-- 创建时序数据库，存传感器监控数据
CREATE TS DATABASE monitoring;
USE monitoring;

CREATE TABLE sensor_data (
    ts TIMESTAMP NOT NULL,
    temperature FLOAT,
    humidity FLOAT
) TAGS (
    device_id INT NOT NULL,
    sensor_type VARCHAR NOT NULL
) PRIMARY TAGS(device_id);

-- 插入时序数据
INSERT INTO sensor_data VALUES
    (NOW(), 25.5, 60.2, 101, 'temperature'),
    (NOW(), 26.1, 58.7, 102, 'temperature');

-- 跨模查询：关联设备信息和最新监控数据
SELECT
    d.device_name,
    d.location,
    s.temperature,
    s.humidity,
    s.ts AS last_update
FROM device_info.devices d
JOIN (
    SELECT DISTINCT ON (device_id)
        device_id, temperature, humidity, ts
    FROM monitoring.sensor_data
    ORDER BY device_id, ts DESC
) s ON d.device_id = s.device_id
WHERE d.status = 'active'
ORDER BY d.device_id;

这种 CREATE TS DATABASE 和 CREATE DATABASE 并存、跨库 JOIN 的能力，正是 KWDB 多模融合的核心卖点。对于物联网场景来说，设备元数据走关系模型，传感器读数走时序模型，一套系统全搞定，架构复杂度直接降维 👉。

06. SampleDB：内置智能电表场景，一键体验

光有空库不够直观，kwcli 还内置了一个 SampleDB 组件，模拟智能电表的真实业务场景。

6.1 初始化与造数据

# 创建数据库和表结构
kwcli sampledb init

# 生成示例数据（100 个电表，10000 条读数）
kwcli sampledb generate

# 检查 SampleDB 是否存在
kwcli sampledb status

输出：

[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli sampledb status
SampleDB Status:
  rdb  database: exists
  tsdb database: exists

6.2 场景查询

# 查看所有内置场景
kwcli sampledb list

# 运行指定场景
kwcli sampledb run top10-area-energy
kwcli sampledb run fault-meters

# 一键跑完所有场景
kwcli sampledb run --all

# 清理数据
kwcli sampledb clean

输出：

[shawnyan@DESKTOP-SHAWN kwcli]$ kwcli sampledb list
Available Smart Meter Scenarios:
------------------------------------------------------------
   1. top10-area-energy         查询区域用电量TOP10
      统计各区域总用电量，取前10名
   2. fault-meters              查询故障电表及用户信息
      查询状态为Fault的电表及其关联的用户信息
   3. meter-summary             电表概要查询
      查询指定电表的详细信息及数据点数量
   4. alarm-detection           告警检测查询
      根据告警规则检测异常数据
   5. area-energy-stats         区域用电量统计
      按区域统计总用电量和平均功率
   6. recent-24h-trend          查询指定电表最近24小时用电趋势量
      查询M1电表最近24小时的功率和能耗
   7. time-bucket-stats         分时负荷统计
      按1小时粒度统计重点电表的功率指标
   8. session-analysis          用电会话分析
      以30分钟空闲间隔划分会话窗口，查看连续用电过程
   9. voltage-state             电压状态持续分析
      按是否高压切分连续区间，观察状态持续时间
  10. abnormal-current          异常电流事件识别
      识别电流升高到6A及以上并回落到5.3A及以下的异常事件
  11. sliding-window            滑动采样趋势分析
      每12条采样做窗口，以6条为滑动步长观察功率变化

Run a scenario:
  kwcli sampledb run <name>
  kwcli sampledb run --all
[shawnyan@DESKTOP-SHAWN kwcli]$

SampleDB 的设计思路很棒：不是给你一张空表让你自己摸索，而是直接给一个完整的业务场景。从 schema 设计、数据生成，到典型查询（Top10 耗电区域、故障电表筛查），一条龙体验下来，你对 KWDB 的时序能力和 SQL 方言就会有很直观的认识。

07. KaiwuDB 社区版 KWDB：这个数据库什么来头？

聊了这么多 kwcli 的使用，是时候正经介绍一下它背后的数据库了。

7.1 产品定位与核心特性

KWDB 是浪潮 KaiwuDB 的开源社区版，2024 年 8 月正式开源，同年 9 月捐赠至开放原子开源基金会孵化运营。它是一款面向 AIoT 场景的分布式多模数据库，核心能力可以概括为：

7.2 版本演进

预计 5 月底将发布 KWDB 3.2。

7.3 与商业版 KaiwuDB 的差异

从开源协议来看，KWDB 采用 MulanPSL2，这是一种对商业友好的国产开源协议。和商业版 KaiwuDB 相比，社区版在核心引擎上是同源的，主要差异体现在企业级特性上：

对于开发者、学生、中小团队来说，KWDB 社区版的功能已经足够覆盖大部分物联网场景的原型验证和中小规模生产。如果需要企业级 SLA、可视化运维、或者大规模集群调优，再考虑商业版也不迟。

08. 总结

写到这里，给大家提炼几点笔者个人的观察和选型建议：

1. 物联网场景的数据库选型，多模融合是大趋势。时序库 + 关系库各装一套的时代正在过去，KWDB 这种"一库多用"的架构，能显著降低系统复杂度和运维成本。KWDB V3.0 跨模查询性能提升了 5~10 倍，这对于需要同时分析设备元数据和传感器时序数据的业务来说，是确有价值的实用特性。

2. 国产时序数据库已经具备国际竞争力。KaiwuDB 在 benchANT 榜单上的表现说明，国产数据库在特定场景下完全可以对标甚至超越 InfluxDB、TimescaleDB 等国际产品，信创选型不必再"唯洋是举"。

3. kwcli 进一步降低了 KWDB 的上手门槛。对于想体验 KWDB 的开发者，建议从 kwcli playground start 开始，30 秒进入学习状态；对于有部署需求的团队，kwcli kwdb install 也能快速搭出开发环境。

Have a nice day ~ ☕

🌻 往期内容 ▼

• Oracle Skills开源：AI工程正在进入"技能时代"
• HOW2026复盘分享：晨章数据EloqData的NVMe+协程实践
• HOW2026大会：PostgreSQL与AI在泉城济南的硬核碰撞
• AWS What's Next峰会全复盘；开启AI操作系统时代，OpenAI正式“入驻”AWS生态
• MySQL 8.0结束生命周期，8.4.9 LTS、9.7.0发版上线：一个时代的交接与新生
• 虚谷数据库发布了一个Skills剧透了新版本特性
• 金仓社区2周年了
• DBClaw与TRAE穿搭指南：数据库诊断工具的正确打开方式
• TiDB Radio | 平凯宇宙新鲜事儿 (2026.03.31)
• 告别古法部署，用 OpenClaw 安装 KaiwuDB 3.1.0 并体验新特性
• 官宣｜星珩联盟，正式启航！
• 苦等三年！Oracle AI Database 26ai本地服务器版终于来了

👉 这里有得聊

如果对国产基础软件（操作系统、数据库、中间件）、AI、Vibe Coding、OpenClaw 、Hermes Agent 等感兴趣，可以加群一起聊聊。关注微信公众号：(少安事务所)，后台回复[群]，即可看到入口。如果这篇文章为你带来了灵感或启发，请帮忙『点赞、推荐、转发』吧，感谢！ღ( ´･ᴗ･` )~