【KWDB 创作者计划】香橙派Ai Pro安装部署KWDB数据库踩坑经验

1. 了解 KWDB

KWDB 是由开放原子开源基金会孵化及运营的开源项目，是一款面向 AIoT 场景的分布式多模数据库产品，支持在同一实例同时建立时序库和关系库并融合处理多模数据，具备千万级设备接入、百万级数据秒级写入、亿级数据秒级读取等时序数据高效处理能力，具有稳定安全、高可用、易运维等特点。

KWDB 基于浪潮 KaiwuDB 分布式多模数据库研发开源，典型应用场景包括但不限于物联网、能源电力、交通车联网、智慧政务、IT 运维、金融证券等，旨在为各行业领域提供一站式数据存储、管理与分析的基座，助力企业数智化建设，以更低的成本挖掘更大的数据价值。

KWDB 为不同角色开发者提供以下支持（包括但不限于）：

为开发者提供通用连接接口，具备高速写入、极速查询、SQL 支持、随需压缩、数据生命周期管理、集群部署等特性，与第三方工具无缝集成，降低开发及学习难度，提升开发使用效率。
为运维管理人员提供快速安装部署、升级、迁移、监控等能力，降低数据库运维管理成本。

关键词：物联网（IoT）、多模数据库、分布式、时序数据处理、云边端协同

2. 部署说明

KWDB部署支持三种方式：

• 单节点裸机部署（不支持aarch64位）
• 单节点容器部署（支持aarch64位）
• 开源版本源码编译（博主编译失败）

下图是KWDB开源版本，点我访问

本次我们将kaiwuDB部署到Orange pi AI Pro 开发板上，使用系统为Ubuntu22.04(aarch64)根据上图，可知不适合裸机部署，所以只剩下源码编译和容器部署，经过测试博主通过源码编译的方式
并未成功，为了能找到原因，将本次失败经历也记录下来，
最后通过Docker完成本地数据库的搭建和基本学习使用。

2.1 KWDB硬件支持

OrangePi Ai Pro配置

规格	参数
CPU	4核（3核+NPU）
内存	8GB
存储	支持NVMe SSD（M.2接口）
系统支持	Ubuntu 22.04 aarch64

✅满足KWDB最低要求4核4G

3. 部署前准备

3.1 香橙派安装Ubuntu22.04系统

3.2 镜像下载

首先根据kaiwuDB下载适合的ubuntu架构和版本，我们这里选择香橙派官方提供的ubuntu22.04镜像

3.3 固件烧录

下载balenaetcher烧录工具，将镜像文件烧录到香橙派中

烧录成功等待验证

验证后不同版本提示信息不一样，免安装版本和直接安装版本，烧录成功提示不同，如果提示失败，请自行重启香橙派测试
绿灯由GPIO4_19控制其亮灭，可以作为SATA硬盘的指示灯或者其他需要的用途。目前发布的Linux系统默认在DTS中将其点亮。当看到此灯点亮后，至少可以说明Linux内核已经启动了。

3.4 进入终端配置基本连接

首次配置可以使用网线连接家用路由器，可以通过路由器的连接信息获取IP地址

使用MoBaxterm SSH连接

账号：root
密码：Mind@123

通过nmcli命令连接WIFI
香橙派上有WIFI模块，于是我们进行Wi-Fi连接，后面就可以不用网线连接开发板

nmcli dev wifi

连接WIFI

sudo nmcli dev wifi connect 'Cloud' password '13*******8'

​1. 查看系统位数（ARM64/aarch64 还是 ARM32）​

uname -m

2. 查看 CPU 核心数

lscpu

​3. 查看内存大小

free -h

4. 开始部署KWDB

4.1 😏单节点容器部署

4.1.1 安装Docker

1. 卸载旧版本（如有）​​

sudo apt remove -y docker docker-engine docker.io containerd runc
sudo apt autoremove -y

2. 安装基础依赖

sudo apt update
sudo apt install -y ca-certificates curl gnupg lsb-release

3. 添加阿里云 Docker CE 镜像源

# 创建GPG密钥目录
sudo mkdir -p /etc/apt/keyrings

# 下载阿里云镜像的GPG密钥（自动验证）
curl -fsSL https://mirrors.aliyun.com/docker-ce/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# 添加阿里云Docker源
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://mirrors.aliyun.com/docker-ce/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# 更新软件源
sudo apt update

4. 安装 Docker 核心组件

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

4.1.2 验证Docker安装

查看版本，确认安装

docker version

4.1.3 设置 Docker 开机自启

sudo systemctl enable docker

4.1.4下载部署代码

下载安装包KWDB-2.2.0-ubuntu22.04-aarch64-docker.tar.gz并上传安装包到开发板

解压

cd /home/upload/
tar -zxvf KWDB-2.2.0-ubuntu22.04-aarch64-docker.tar.gz

4.1.5 配置deploy.cfg

默认情况下，deploy.cfg 配置文件中包含集群配置参数，请删除或注释 [cluster] 集群配置项。

不需要集群的话注释 [cluster]以下内容，例如：

[global]
secure_mode=tls
management_user=kaiwudb
rest_port=8080
kaiwudb_port=26257
data_root=/var/lib/kaiwudb
#cpu=1
encrypto_store=true

[local]
node_addr=127.0.0.1

# [cluster]
# # node_addr=127.0.0.2,127.0.0.3
# # ssh_port=22
# # ssh_user=admin

1.进入刚刚解压好的安装包内，输入代码进入编辑

vi deploy.cfg

输入"i"进入编辑模式

输入完成后，按下"esc"输入":wq"回车保存退出

4.1.6 为deploy.sh 脚本增加运行权限

cd kwdb_install
chmod +x ./deploy.sh

4.1.7 执行单机部署安装命令

./deploy.sh install --single

4.1.8 安装成功

根据系统提示重新加载 systemd 守护进程的配置文件

systemctl daemon-reload

4.1.9 启动 KaiwuDB 节点

./deploy.sh start

4.1.10 配置 KaiwuDB 开机自启动

systemctl enable kaiwudb

4.1.11 查看KWDB服务状态

./deploy.sh status

提示：
香橙派（3核 + NPU）但是显示只有3个cpu，安装后可能会运行不起来，需要通过./deploy.sh install --single --force安装即可，或者更改deploy.sh中的cpu核心检测，–force 参数跳过了 CPU 核数检查，实际运行证明 ​3核足够支撑基础服务

4.1.12 创建用户

接下来就是连接数据库了，不过在此之前我们需要先创建用户账号（KWDB官方文档中【快速上手】没有注明该操作，该操作位于【集群部署->单节点容器部署】）

进入kwdb_install内输入指令，会询问设置的账号密码设置，回车确认即可

./add_user.sh

例如：

账号：orange
密码：123456

4.2 😭源码编译安装（本小节为失败案例，仅供借鉴参考，可跳过）

该部分安装失败，作为失败案例借鉴参考，可能是机器架构不一样导致的，个人认为是go环境没有用aarch64导致的

4.2.1 下载及上传安装包

1、下载 CMake 安装包(cmake-3.23.4-linux-aarch64.tar.gz)

2、下载Go 安装包（go1.22.5.linux-arm64.tar.gz）

将两个包上传到开发板上

4.2.2 解压安装包

cd /home/upload/

tar -C /usr/local/ -xvf cmake-3.23.4-linux-aarch64.tar.gz

mv /usr/local/cmake-3.23.4-linux-aarch64 /usr/local/cmake

go安装包

tar -C /usr/local -xvf go1.22.5.linux-arm64.tar.gz

创建用于存放项目代码的代码目录

mkdir -p /home/go/src/gitee.com

设置 Go 和 CMake 的环境变量

export GOROOT=/usr/local/go
export GOPATH=/home/go      #请以实际代码下载存放路径为准，在此以home/go目录为例
export PATH=$PATH:/usr/local/go/bin:/usr/local/cmake/bin

使变量设置立即生效

source /etc/profile                           

4.2.4 下载源代码

git clone https://gitee.com/kwdb/kwdb.git /home/go/src/gitee.com/kwbasedb #请勿修改目录路径中的 src/gitee.com/kwbasedb
cd /home/go/src/gitee.com/kwbasedb 
git submodule update --init  #适用于首次拉取代码
git submodule update --remote

构建和安装
在项目目录下创建并切换到构建目录。

cd /home/go/src/gitee.com/kwbasedb
mkdir build && cd build

运行 CMake 配置。
需要在包含 CMakeLists.txt 的 ​构建目录 中运行

cmake .. -DCMAKE_BUILD_TYPE=Release

报错：

找到"/home/go/src/gitee.com/kwbasedb/CMakeFiles/CMakeOutput.log".

The system is: Linux - 5.10.0+ - aarch64

根据日志信息，系统是 ​Linux aarch64（ARM64架构）​，但CMake找不到合适的编译工具链

4.2.5 安装ARM64专用编译工具链

sudo apt update

又遇到报错：
从错误信息来看，使用华为云镜像源 (repo.huaweicloud.com) 时遇到了 ​Hash Sum mismatch​ 问题，这通常是由于镜像源同步延迟或网络问题导致的。

换阿里云镜像源

sudo sed -i 's|http://repo.huaweicloud.com|http://mirrors.aliyun.com|g' /etc/apt/sources.list
sudo apt update

sudo apt install -y build-essential gcc-aarch64-linux-gnu g++-aarch64-linux-gnu

继续报错：

4.2.6 重新运行 CMake

cd /home/go/src/gitee.com/kwbasedb/build
rm -rf *
cmake .. -DCMAKE_BUILD_TYPE=Debug

CMake 配置失败的主要原因是 ​缺少 Protobuf（Protocol Buffers）库

4.2.7 安装 Protobuf 依赖

sudo apt update
sudo apt install -y libprotobuf-dev protobuf-compiler

4.2.8 重新运行

cd /home/go/src/gitee.com/kwbasedb/build
rm -rf *
cmake .. -DCMAKE_BUILD_TYPE=Release  # 注意去掉空格

运行成功

4.2.9 禁用Go模块功能

系统全局设置（需要 root 权限）：修改/etc/profile文件

export GO111MODULE=off

生效

source /etc/profile

4.2.10 编译和安装项目

make

报错

主要错误：
（1）符号重复定义（最紧急）
（2）execgen生成失败
（3）autoconf版本警告（可忽略）

修复

系统全局设置（需要 root 权限）：修改/etc/profile文件

export GO111MODULE=on

go mod edit -replace github.com/emmansun/gmsm/internal/bigmod=./vendor/github.com/emmansun/gmsm/internal/bigmod

5. 使用 KWDB 开发者中心连接 KWDB

5.1 下载连接工具

可以通过命令进行连接操作🔗，不过我认为可视化更加容易理解和使用，这里推荐下载数据库连接工具（点击这里下载KaiwuDB_Developer_Center-2.0.4-win-x86_64.zip）

下载完成后进行解压，双击exe文件即可

接下来我们完成连接

5.2 新建连接

5.3 选择连接类型

5.4 输入账密完成连接

主机输入你的部署服务器的IP，外网服务器的话直接用公网IP即可，输入账号密码点击测试连接，连接成功即可进入数据库管理。

6. 数据库类型

KWDB有两种数据库类型，分别是时序数据库和关系数据库，由于我们后面还有项目案例，根据项目的需求，确定方案用关系型数据库

6.1 时序数据库

时序数据库是专门为处理时间序列数据优化的数据库系统，在KWDB中主要用于：

存储特点：按时间顺序记录的数据点（如传感器数据、监控指标、日志等）

典型结构：通常包含时间戳、指标名称和数值三要素

优势：

🥝高效处理高频率写入

🥝优秀的时间范围查询性能

🥝自动数据降采样和保留策略

🥝针对时间序列的压缩算法

常用于存储设备运行数据、生产指标等时间相关的监测数据。

6.2 关系数据库

关系数据库是使用关系模型组织的传统数据库，在KWDB中用于：

存储特点：以表格形式存储数据，表与表之间可建立关系

核心概念：表、行、列、主键、外键、索引等

优势：

🥝数据结构化程度高

🥝支持复杂的SQL查询

🥝完善的ACID事务支持

🥝数据一致性强

常用于存储设备信息、工单记录、用户权限等结构化业务数据。

7. 数据库操作

7.1 新建数据表

7.1.1 可视化创建

7.1.2 SQL创建

CREATE TABLE goods(
	id INT8 DEFAULT unique_rowid(),
	goods_name VARCHAR(60) NULL,
	production_date VARCHAR(50) NULL,
	shelf_life_days VARCHAR(50) NOT NULL,
	bar_code VARCHAR(50) NOT NULL,
	goods_src STRING NULL,
	FAMILY "primary" (rowid, id, goods_name, production_date, shelf_life_days, bar_code, goods_src)
);
COMMENT ON COLUMN goods.id IS 'id';
COMMENT ON COLUMN goods.goods_name IS '商品名称';
COMMENT ON COLUMN goods.production_date IS '生产日期';
COMMENT ON COLUMN goods.shelf_life_days IS '保质期';
COMMENT ON COLUMN goods.bar_code IS '条形码';
COMMENT ON COLUMN goods.goods_src IS '商品图片';

7.2 增删查改（SQL）

打开SQL编辑器

7.2.1 插入数据

-id指定
INSERT INTO goods VALUES (1, '卫龙亲嘴道麻辣条50g/包', '2025-04-11', '150天', '6935284412079', 'http://app2.showapi.com/img/barCode_img/20200316/ce6a775b-330b-4ee9-b31d-16576412511e.jpg');

或

-id自增
INSERT INTO goods (goods_name, production_date, shelf_life_days,bar_code,goods_src) VALUES ('卫龙亲嘴道麻辣条50g/包', '2025-04-11', '150天', '6935284412079', 'http://app2.showapi.com/img/barCode_img/20200316/ce6a775b-330b-4ee9-b31d-16576412511e.jpg');

7.2.2 删除数据

Delete FROM goods WHERE id='2';

7.2.3 查询数据

SELECT * FROM "ProductData".public.goods;

7.2.4 修改数据

UPDATE "ProductData".public.goods
	SET goods_name='test'
	WHERE id='1';

8. 使用 Python连接 KaiwuDB

以上教程已经创建好了数据库，接下来我们使用python代码连接KWDB，实现增删查改测试，以便于后续的项目开发，修改下面的连接信息以及数据库名字段等内容运行即可：

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-

import psycopg2


def main():
    try:
        con = psycopg2.connect(database="defaultdb", user="test", password="KWdb!2022", host="127.0.0.1",port="26257")
        # for secure connection mode
        # con = psycopg2.connect(database="defaultdb", user="root", password="", host="127.0.0.1",
        #                        port="26257", sslmode="verify-ca",
        #                        sslrootcert=<file_path_of_root_ca_certificate file>,
        #                        sslcert=<file_path_of_user_certificate_file>,
        #                        sslkey=<file_path_of_user_certificate_key>)
        print("Connected!")
        con.set_session(autocommit=True)
        cur = con.cursor()
    except psycopg2.Error as e:
        print(f"Failed to connect to Kaiwudb: {e}")

    sql = "CREATE TABLE db_TimeSeries.table1 \
        (k_timestamp timestamp NOT NULL, \
        voltage double, \
        current double, \
        temperature double \
        ) TAGS ( \
        number int NOT NULL) \
        PRIMARY TAGS(number) \
        ACTIVETIME 3h"
    try:
        cur.execute(sql)
    except psycopg2.Error as e:
        print(f"Failed to create table: {e}")

    sql = "INSERT INTO db_TimeSeries.table1  \
        VALUES ('2024-07-01 10:00:00', 220.0, 3.0, 20.5,123)"
    try:
        cur.execute(sql)
    except psycopg2.Error as e:
        print(f"Failed to insert data: {e}")

    sql = "SELECT * from db_TimeSeries.table1"
    try:
        cur.execute(sql)
        rows = cur.fetchall()
        for row in rows:
            print(f"k_timestamp: {row[0]}, voltage: {row[1]}, current: {row[2]}, temperature: {row[3]}, number: {row[4]}")
    except psycopg2.Error as e:
        print(f"Failed to insert data: {e}")


    cur.close()
    con.close()
    return


if __name__ == "__main__":
    main()

9. 最后

KWDB 是一款开源的分布式多模数据库，支持自适应时序引擎、预测分析引擎等多种数据模型，具有高性能、低成本、多场景的特点。KaiwuDB 覆盖工业物联网、数字能源、车联网、智慧矿山等行业领域，提供稳定安全、高性能、易运维的创新数据软件与服务，本次部署到香橙派Ubuntu(aarch64)上，实现数据本地化存储，为后续结合KWDB出一个项目结合案例做准备