lfedge/ekuiper

Dockerfile 链接

• https://github.com/lf-edge/ekuiper/blob/master/deploy/docker/Dockerfile

快速参考

• 获取帮助：

  官方网站

  • [***]

  GitHub 仓库

  • https://github.com/lf-edge/ekuiper

  文档

  • 快速开始
  • 参考指南

• 提交问题： https://github.com/lf-edge/ekuiper/issues

• 支持的架构 amd64、arm64v8、arm32v7、i386

• 支持的 Docker 版本： https://github.com/docker/docker-ce/releases/latest

什么是 eKuiper

LF Edge eKuiper 是一款轻量级物联网数据分析与流处理引擎，运行于资源受限的边缘设备。其主要目标是在边缘侧提供类似 Apache Flink 的流处理框架。eKuiper 的 规则引擎 允许用户通过 SQL 或图形化（类似 Node-RED）规则，在几分钟内创建物联网边缘分析应用。

!eKuiper 架构图

应用场景

可运行于多种物联网边缘场景，例如：

• 工业物联网（IIoT）中生产线数据的实时处理
• 车联网（IoV）中连接车辆的网关分析 CAN 总线数据
• 智能能源领域中风力发电机和智能储能设备数据的实时分析

在边缘侧进行 eKuiper 处理可显著降低系统响应延迟、节省网络带宽和存储成本，并提升系统安全性。

特性

• 轻量级

  • 核心服务包仅约 4.5M，内存占用约 10MB

• 跨平台

  • CPU 架构：X86 AMD 32/64 位；ARM 32/64 位；PPC
  • 支持主流 Linux 发行版、OpenWrt Linux、MacOS 和 Docker
  • 适配工业 PC、树莓派、工业网关、家庭网关、MEC 边缘云服务器

• 数据分析支持

  • 支持数据 ETL 操作
  • 支持数据排序、分组、聚合，以及与不同数据源（数据库、文件数据）的关联
  • 60 余种函数，包括数学、字符串、聚合和哈希等类型
  • 4 种时间窗口和计数窗口

• 高度可扩展 支持通过 Golang 或 Python 扩展 Source（数据源）、Functions（函数）和 Sink（数据目标）：

  • Source：允许用户添加更多分析数据源
  • Sink：允许用户将分析结果发送至自定义系统
  • UDF 函数：允许用户添加自定义数据分析函数（如 AI/ML 函数调用）

• 管理能力

  • https://hub.docker.com/r/emqx/ekuiper-manager%EF%BC%8C%E6%94%AF%E6%8C%81%E5%8F%AF%E8%A7%86%E5%8C%96%E7%AE%A1%E7%90%86
  • 通过命令行界面（CLI）、REST API 和配置映射（Kubernetes）管理插件、流和规则
  • 易于集成 Kubernetes 框架，如 https://github.com/kubeedge/kubeedge%E3%80%81OpenYurt%E3%80%81https://github.com/rancher/k3s%E3%80%81https://github.com/baetyl/baetyl

• 与 EMQX 产品集成 与 EMQX、Neuron 和 NanoMQ 无缝集成，提供从工业物联网、车联网等场景的端到端解决方案

如何使用本镜像

运行 eKuiper

在本 Docker 镜像下执行命令：

shell
docker run -d -v `pwd`:$somewhere lfedge/ekuiper:$tag $somecommand

示例：

shell
docker run -p 9081:9081 -d --name ekuiper -e MQTT_SOURCE__DEFAULT__SERVER="$MQTT_BROKER_ADDRESS" lfedge/ekuiper:$tag

注意：在 v1.5.0 版本前，MQTT 服务器属性为数组类型。详情请查看 迁移指南。

5 分钟快速开始

1. 将 eKuiper 数据源设置为 MQTT 服务器。本示例使用公共 MQTT 测试服务器 tcp://broker.emqx.io:1883（由 EMQ 提供）。

   shell
   

docker run -p 9081:9081 -d --name ekuiper -e MQTT_SOURCE__DEFAULT__SERVER="tcp://broker.emqx.io:1883" lfedge/ekuiper:$tag

2. 创建流 — 流定义流数据的 schema，类似数据库中的表定义。假设温度和湿度数据发送至 `broker.emqx.io`，并将在本地运行的 eKuiper 容器中处理。以下步骤创建名为 `demo` 的流，数据发送至 `devices/device_001/messages` 主题（`device_001` 可替换为其他设备，如 `device_002`，所有设备数据均由 `demo` 流订阅处理）。

   ```shell
# 在主机执行
docker exec -it ekuiper /bin/sh

# 在容器内执行
bin/kuiper create stream demo '(temperature float, humidity bigint) WITH (FORMAT="JSON", DATASOURCE="devices/+/messages")'
Connecting to 127.0.0.1:20498...
Stream demo is created.

bin/kuiper query
Connecting to 127.0.0.1:20498...
kuiper > select * from demo where temperature > 30;
Query was submit successfully.

3. 使用 MQTT 客户端（如 MQTT X）向 broker.emqx.io 的 devices/device_001/messages 主题发布传感器数据：

   shell
   

mqttx pub -h broker.emqx.io -m '{"temperature": 40, "humidity" : 20}' -t devices/device_001/messages

4. 若一切正常，在 `bin/kuiper query` 窗口将显示消息。尝试发布温度低于 30 的消息，将被 SQL 的 WHERE 条件过滤：

kuiper > select * from demo WHERE temperature > 30; [{"temperature": 40, "humidity" : 20}]

   若有问题，请查看 `log/stream.log` 日志。

5. 按 `ctrl + c` 停止 `bin/kuiper query` 命令控制台以结束测试。

您也可参考 https://github.com/lf-edge/ekuiper/blob/master/docs/en_US/operation/manager-ui/overview.md 获得更好的使用体验。

如需探索 eKuiper 更多功能，可参考以下边缘侧应用及与 AWS/Azure IoT 云平台集成方案：
- 轻量级边缘计算 eKuiper 与 Azure IoT Hub 集成方案
- 轻量级边缘计算 eKuiper 与 AWS IoT Hub 集成方案

# 镜像变体

`lfedge/ekuiper` 镜像提供多种版本，适用于不同场景：

## `lfedge/ekuiper:<tag>`

默认镜像。若不确定需求，建议使用此版本。自 1.7.1 版本起，它是 `lfedge/ekuiper:<tag>-alpine`（见下文）的别名；此前版本等同于 `lfedge/ekuiper:<tag>-dev` 镜像。

## `lfedge/ekuiper:<tag>-alpine`

基于 Alpine Linux（https://hub.docker.com/_/alpine）构建，体积更小（约 5MB 基础镜像）。适合对镜像大小有严格要求的场景。注意其使用 musl libc 而非 glibc，部分软件可能存在兼容性问题，但多数场景下可安全使用。如需额外工具，需在 Dockerfile 中自行安装（参考 https://hub.docker.com/_/alpine/）。

## `lfedge/ekuiper:<tag>-slim`

基于 Debian 构建，仅包含运行 eKuiper 所需的最小依赖包。与开发镜像（`lfedge/ekuiper:<tag>-dev`）的区别是不含 Golang 开发环境，推荐用于部署已编译的自定义插件。

## `lfedge/ekuiper:<tag>-slim-python`

在 slim 版本基础上增加 Python 环境，推荐用于运行 eKuiper Python 可移植插件。

## `lfedge/ekuiper:<tag>-dev`

开发环境镜像，基于 Debian 并包含 Golang 构建环境。适合临时容器（挂载源码编译插件、运行应用）或作为基础镜像构建其他镜像。注意此镜像体积最大，通常用于开发场景。

注意：此镜像等效于 0.3.x 版本中的 `x.x.x-dev` 开发镜像。

# 配置

eKuiper 支持通过环境变量修改容器内配置文件。环境变量需按指定格式设置，例如：

KUIPER__BASIC__DEBUG => 对应 etc/kuiper.yaml 中的 basic.debug MQTT_SOURCE__DEMO_CONF__QOS => 对应 etc/mqtt_source.yaml 中的 demo_conf.qos

环境变量通过两个下划线（__）分隔，第一部分匹配配置文件名，其余部分匹配配置项的层级结构。

# 迁移指南

自 1.5.0 版本起，eKuiper 将 MQTT 源代理配置从 `servers`（数组）改为 `server`（单地址），用户仅能配置一个 MQTT 代理。若使用旧版本并通过环境变量配置 MQTT 源地址，需将环境变量从 `MQTT_SOURCE__DEFAULT__SERVERS=[tcp://broker.emqx.io:1883]` 修改为 `MQTT_SOURCE__DEFAULT__SERVER="tcp://broker.emqx.io:1883"`。

# 关于 EdgeX

`etc/sources/edgex.yaml` 的配置内容与 EdgeX core data 服务的 `cmd/core-data/res/configuration.toml` 相关，例如：

[MessageQueue] Protocol = 'tcp' Host = '*' Port = 5563 Type = 'zero' Topic = 'events'

[Service] ... Host = 'localhost' Port = 48080 ...

如需配置更多选项，可将配置文件挂载到 eKuiper 容器：

docker run --name ekuiper -v /path/to/mqtt_sources.yaml:/kuiper/etc/mqtt_sources.yaml -v /path/to/edgex.yaml:/kuiper/etc/sources/edgex.yaml lfedge/ekuiper:$tag

# 更多信息

如需了解项目详情，请参考 https://github.com/lf-edge/ekuiper/blob/master/docs/en_US/README.md。