title: Mac玩转kaiwudb数据库时遇到的坑，顺手提交一个 PR。 date: 2026-03-02

你好，我是悟空。

一、前言

最近正在学习 KWDB 数据库，为了更好地掌握这款数据库的使用和底层原理，首先得安装这款数据库，我常用的电脑是 MAC（M1 芯片），网上和官方文档上都没有这方面的实践教程，所以我详细记录了Mac M1 部署 kaiwudb 数据库遇到的坑。

下文记录了我在Mac M1上折腾KaiwuDB数据库，遇到了镜像拉取、管理工具报损坏等一系列坑，都一一解决了。顺手给官方文档提了个PR修bug，最后成功演示了时序数据、关系数据的存储和跨模查询，验证了这款多模数据库的核心功能。

二、KWDB 简介

KaiwuDB 简称 KWDB，它是一款面向 AIoT 场景的分布式、多模融合的数据库产品, 支持同一实例同时建立时序库和关系库并融合处理多模数据，具备时序数据高效处理能力，具有稳定安全、高可用、易运维等特点。面向工业物联网、数字能源、车联网、智慧产业等领域，KWDB 提供一站式数据存储、管理与分析的基座。

KWDB 特点

• 更高的处理性能：海量数据处理能力、高速查询响应、丰富的时序查询功能。

• 更低的运管成本：多模数据统一管理、业务数据融合。

• 更低的存储成本：智能压缩技术、生命周期管理

多模数据库

KWDB 的一个非常重要的特点就是它是多模数据库，KaiwuDB 深度融合了自适应时序引擎、事务处理引擎和预测分析引擎，支持在同一实例同时建立时序库和关系库并融合处理多模数据，属于多模数据库。

时序库

• 时序库：用于存储和管理时序数据的数据库对象（Time Series Database）。同一数据库实例可以创建一个或多个时序库。时序库只包含时序表。

• 时序表：在时序库下建立的数据表（Time Series Table）。每个时序库下可以创建多张时序表。除字段外，时序表还需要包括时间戳列和标签列。时间戳列用于记录数据采集的时间。标签列用于记录采集对象的静态数据。字段用于记录采集对象的实时数据。

关系库

• 关系库：用于存储和管理关系数据的数据库对象（Relational Database）。同一数据库实例可创建一个或多个关系库。每个关系库包括关系表、视图、索引等对象。

• 关系表：在关系库下创建的数据表（Base Table）。每个关系库下可以创建多张关系表，表中的每列为一个字段，每行为一条记录。

KWDB 架构

相比传统的数据库，KaiwuDB 提供多模数据管理能力，支持不同数据模型的统一存储，助力企业跨部门、跨业务统一管理数据，实现多业务数据融合，支撑多样化的应用服务。KaiwuDB 的产品架构如下图所示：

三、MAC M1 安装 KWDB

拉取 KWDB 镜像

MAC M1 属于 ARM64 架构，可以通过容器化的方式安装，按照官方文档的方式，到仓库的 release 页面找到相关的包，未找到 docker 镜像包，然后联系了 KWDB 的技术支持人员，可以通过 docker 拉取镜像的方式。

然后就用这个命令去获取镜像：

docker pull kwdb/kwdb:latest

使用 docker-compose 启动 KWDB 容器

在本地创建 docker-compose.yml 文件

version: '3.3'
services:
  kaiwudb-container:
    image: "kwdb/kwdb:latest"
    container_name: kaiwudb-experience
    hostname: kaiwudb-experience
    ports:
      - 8020:8080
      - 26257:26257
    ulimits:
      memlock: -1
    networks: 
      - default
    restart: on-failure
    ipc: shareable
    privileged: true
    environment:
      - LD_LIBRARY_PATH=/kaiwudb/lib
    tty: true
    working_dir: /kaiwudb/bin
    command: 
      - /bin/bash
      - -c
      - |
        /kaiwudb/bin/kwbase start-single-node --insecure --listen-addr=0.0.0.0:26257 --advertise-addr=127.0.0.1:26257 --http-addr=0.0.0.0:8020 --store=/kaiwudb/deploy/kaiwudb

注意：因本地 8080 端口被其他容器占用了，所以改成了 8020 端口。

通过命令 docker-compose up -d 启动，如下图所示：

下载 KaiwuDB Developer Center

KaiwuDB Developer Center（KaiwuDB 开发者中心）是专门为 KWDB 数据库系统量身定制的可视化管理工具。

下载地址如下：

https://gitee.com/kwdb/kwdb/releases

下载之后双击打开，提示文件已损坏：

联系了 KWDB 的技术支持人员后，顺利解决。

解决方案：

以下方法可以绕过 Ventura 的限制，但请注意安全风险，仅限可信来源的程序。
 (1) 允许未签名应用运行

步骤： 
解压 .tar.gz 文件（双击或用 tar -xzf yourfile.tar.gz）。
尝试运行程序，若提示“已损坏”，在终端执行： 
sudo spctl --master-disable
 这会临时禁用 Gatekeeper。

再次运行程序： 
open /path/to/your/app

如果仍提示“已损坏”，强制允许： 
sudo xattr -r -d com.apple.quarantine /path/to/your/app
 这会移除文件的隔离属性。

完成后恢复 Gatekeeper： 
sudo spctl --master-enable

再次双击就能正常打开了，如下图所示，界面有点像 DBeaver 管理工具的界面。

四、给官方文档提交 PR

为了回馈社区，我将官方文档中过时的信息进行了调整，并提交了一个 PR（Pull Request）。

还得到了官方人员的修改建议，太感动了。

五、时序数据操作

创建时序库、时序表、时序数据

时序库：monitoring

时序表：device_heartbeats

标签：device_id

创建时序数据：

查询时序表

ｓｅｌｅｃｔ * from monitoring.public.device_heartbeats

六、关系数据操作

创建关系数据库、关系数据表、关系数据

数据库：device

数据表：device_info

查询关系数据

七、跨模查询

跨模查询关系数据表的设备信息和时序数据表的心跳信息。

ｓｅｌｅｃｔ * from "device".public.device_info device 
inner join monitoring.public.device_heartbeats hb 
on device.id = hb.device_id