Docker 部署

CycBox 提供 Docker 镜像，用于在服务器、边缘网关和 CI 流水线等无界面环境中运行工作流。当您需要部署自动化的 IoT 工作流而不需要图形界面时，这非常有用。

概述

CycBox 可以将完整的工作流（包括 Lua 脚本逻辑和连接配置）导出为单个 .lua 文件。该文件可以直接使用 cycbox-cli 二进制程序运行，也可以在 Docker 容器中运行。

导出的 Lua 配置文件

CycBox Lua 配置文件包含 Lua 脚本代码和嵌入在多行注释中的 JSON 配置块。例如：

-- EID041 Modbus 温湿度传感器到 MQTT 发布器

local SLAVE_ADDR = 3
local POLL_INTERVAL = 5000
local MQTT_TOPIC = "cycbox/eid041"
local MQTT_CONNECTION_ID = 1

function on_start()
  log("info", "=== EID041 Modbus Sensor Script Started ===")
end

local last_poll_time = 0
function on_timer(elapsed_ms)
  if elapsed_ms - last_poll_time >= POLL_INTERVAL then
    modbus_rtu_read_input_registers(SLAVE_ADDR, 0x0000, 6, 0, 0)
    last_poll_time = elapsed_ms
  end
end

function on_receive()
  -- 处理消息 ...
  return true
end

--[[
{
  "version": "1.8.1",
  "name": "EID041 Modbus RTU to MQTT",
  "configs": [
    {
      "app": {
        "app_transport": "serial",
        "app_codec": "modbus_rtu_codec"
      },
      "serial": {
        "serial_port": "/dev/ttyUSB0",
        "serial_baud_rate": 9600
      }
    },
    {
      "app": {
        "app_transport": "mqtt"
      },
      "mqtt": {
        "mqtt_broker_url": "mqtt://broker.emqx.io:1883",
        "mqtt_client_id": "cycbox_eid041"
      }
    }
  ]
}
]]

JSON 块定义了连接（传输层、编解码器及其参数），而上方的 Lua 代码实现了运行时逻辑。您可以从 CycBox 图形界面导出此文件，也可以手动编写。

使用 Docker 运行

CycBox Docker 镜像托管在 ghcr.io/cycbox/cycbox:latest，支持 amd64 和 arm64 架构。

快速开始

docker run --rm \
  -v ./config.lua:/config/config.lua:ro \
  ghcr.io/cycbox/cycbox:latest

这会将本地的 config.lua 挂载到容器中并运行。

访问串口设备

要访问主机上的串口设备（例如 /dev/ttyUSB0），需要以特权模式运行容器并挂载 /dev：

docker run --rm \
  --privileged \
  -v /dev:/dev \
  -v ./config.lua:/config/config.lua:ro \
  ghcr.io/cycbox/cycbox:latest

或者，只传入特定设备：

docker run --rm \
  --device /dev/ttyUSB0 \
  -v ./config.lua:/config/config.lua:ro \
  ghcr.io/cycbox/cycbox:latest

使用自定义配置路径

默认情况下，cycbox-cli 读取 /config/config.lua。如需使用其他路径：

docker run --rm \
  -v ./my_workflow.lua:/app/my_workflow.lua:ro \
  ghcr.io/cycbox/cycbox:latest \
  --config /app/my_workflow.lua

启用调试日志

docker run --rm \
  -v ./config.lua:/config/config.lua:ro \
  ghcr.io/cycbox/cycbox:latest \
  --config /config/config.lua --debug

使用 Docker Compose 运行

对于持久化部署，推荐使用 Docker Compose。创建 compose.yaml 文件：

services:
  cycbox:
    image: ghcr.io/cycbox/cycbox:latest
    container_name: cycbox
    # 访问主机串口设备需要特权模式
    privileged: true
    volumes:
      - /dev:/dev
      - ./config.lua:/config/config.lua:ro
    restart: unless-stopped

然后启动服务：

docker compose up -d

常用命令

# 查看日志
docker compose logs -f cycbox

# 停止服务
docker compose down

# 更新 config.lua 后重启
docker compose restart cycbox

停止

cycbox-cli 能够优雅地处理 SIGINT 和 SIGTERM 信号，因此 docker stop 和 Ctrl+C 都会正常关闭引擎。