kesi

kesi 通用驱动/服务安装程序 - 自动下载、配置和运行 kesi 驱动和服务

快速开始

使用 npx（推荐）

# 安装并运行指定驱动或服务
npx kesi <名称>

# 示例：安装 Modbus 驱动
npx kesi modbus

# 示例：安装 kesi 服务
npx kesi kesi

# 示例：安装 OPC-UA 驱动
npx kesi opcua

# 传递数据配置（仅驱动）
npx kesi modbus -d '{"id":"设备ID","name":"modbus","groupId":"分组ID","driverType":"modbus","runMode":"one","device":{"settings":{"interval":60,"ip":"设备IP","port":502,"unit":1}},"autoReload":{"disable":true},"autoUpdateConfig":true,"tables":[{"id":"modbus2","device":{"settings":{"autoAddr":true,"interval":5,"ip":"设备IP"},"tags":[{"area":3,"dataType":"Int32BE","id":"p1","name":"p1","offset":1,"policy":"save"}],"commands":[{"name":"cmd1","ops":[{"area":"coil","dataType":"Boolean","offset":1,"param":"cmd1"}]}]},"devices":[{"id":"modbus21","name":"modbus21","settings":{"unit":7}}]}]}'

# 强制更新到最新版本
npx kesi modbus --update

全局安装

# 全局安装
npm install -g kesi

# 运行驱动或服务
kesi <名称>

命令参数

| 参数 | 简写 | 说明 | |------|------|------| | <名称> | - | 要安装的驱动或服务名称（必需） | | --data <json> | -d | 传递 data.json 配置数据（仅驱动） | | --update | -u | 强制重新下载并更新 |

下载地址

• 下载基地址固定为 https://d.gtsiot.cn
• 实际下载地址按 ${base}/${projectInfo.name}/${projectInfo.tag_name}/${asset.name} 拼接
• 如果固定地址下载失败，会自动回退到 latest 接口返回的原始资产地址重试

支持的类型

kesi 支持安装两种类型：

驱动 (driver)

• 数据采集驱动程序
• 需要配置 config.yaml
• 支持 -d 参数传递数据配置

服务 (server)

• kesi 平台服务
• 使用安装包自带的 service.yaml
• 不支持 -d 参数

常用项目

驱动:

• modbus - Modbus TCP 驱动
• opcua - OPC UA 驱动
• mqtt - MQTT 驱动

服务:

• kesi - kesi 核心服务
• 更多服务请查看 API

运行方式

驱动和服务会根据平台自动选择下载包与启动方式：

• Windows: 下载 windows 包（不带 binary）并使用 PM2 启动
• Linux x86_64/aarch64: 优先下载 -binary 包并使用 PM2 启动
• macOS: 优先下载 -binary 包并使用 PM2 启动
• Linux loong64（龙芯）: 使用 Docker 包并通过 Docker 启动

自动启动

• PM2 启动后会自动保存进程列表

• 如需开机自启动，请在首次安装后运行：

  npx pm2 startup

  然后按照提示执行生成的命令

• Docker 模式（loong64）容器默认使用 --restart unless-stopped

配置文件

驱动配置

驱动启动时会自动生成 etc/config.yaml 配置文件：

http:
  host: 0.0.0.0
  port: 8080

driverGrpc:

mq:
  type: local
  local:
    logPublish: true
    logConsume: true
    showPayload: false

driver:
  id: <项目名称>
  name: <驱动显示名称>
  timeout: 10
  idle: 30

服务配置

服务使用安装包自带的 service.yaml 配置文件，包含完整的服务配置（数据库、缓存、MQ、认证等）。

目录结构

kesi/lib/<group_name>/<名称>/
├── .version          # 当前安装版本
├── archive/          # 下载缓存
└── extracted/        # 程序文件
    ├── etc/
    │   └── config.yaml 或 service.yaml
    └── <程序文件>    # 二进制文件

其中 <group_name> 是项目的分组名称（driver 或 server），根据 API 返回的 group_name 字段自动确定。

运行方式

驱动会根据平台自动选择下载包与启动方式：

• Windows: 下载 windows 包（不带 binary）并使用 PM2 启动
• Linux x86_64/aarch64: 优先下载 -binary 包并使用 PM2 启动
• macOS: 优先下载 -binary 包并使用 PM2 启动
• Linux loong64（龙芯）: 使用 Docker 包并通过 Docker 启动

自动启动

• PM2 启动驱动后会自动保存进程列表

• 如需开机自启动，请在首次安装后运行：

  npx pm2 startup

  然后按照提示执行生成的命令

• Docker 模式（loong64）容器默认使用 --restart unless-stopped

前置要求

macOS/Windows/Linux(x86_64/aarch64):

npm install -g pm2

Linux loong64:

# 安装 Docker
curl -fsSL https://get.docker.com | sh

配置文件

驱动启动时会自动生成 etc/config.yaml 配置文件：

http:
  host: 0.0.0.0
  port: 8080

driverGrpc:

mq:
  type: local
  local:
    logPublish: true
    logConsume: true
    showPayload: false

driver:
  id: <项目名称>
  name: <驱动显示名称>
  timeout: 10
  idle: 30

目录结构

kesi/lib/<group_name>/<项目名称>/
├── .version          # 当前安装版本
├── archive/          # 下载缓存
└── extracted/        # 驱动文件
    ├── etc/
    │   └── config.yaml
    └── <项目文件>    # 二进制文件

其中 <group_name> 是驱动的分组名称（如 driver），根据 API 返回的 group_name 字段自动确定。

故障排除

端口被占用

如果 8080 端口被占用，驱动会自动使用下一个可用端口（8081、8082...）。

驱动不存在

如果指定的项目名称不存在，会显示错误信息：

错误: 未找到驱动: xxx

请检查项目名称是否正确，或使用 --list 参数查看所有可用项目。

常见启动问题

# 查看 PM2 运行状态
pm2 list

# 查看 PM2 日志
pm2 logs <项目名称>-driver

# 停止驱动
pm2 stop <项目名称>-driver

# 重启驱动
pm2 restart <项目名称>-driver

# 删除驱动
pm2 delete <项目名称>-driver

# 配置开机自启动（仅首次需要）
npx pm2 startup

# 保存当前进程列表
pm2 save

loong64 Docker 相关问题

# 查看运行中的容器
docker ps

# 查看容器日志
docker logs <项目名称>-driver

# 停止容器
docker stop <项目名称>-driver

# 删除容器
docker rm <项目名称>-driver

版本管理

驱动会自动从 API 获取最新版本信息：

• 首次运行：自动下载对应平台版本
• 版本相同：使用已缓存的文件
• 使用 --update 参数：强制重新下载最新版本

许可证

MIT

支持

• 问题反馈: GitHub Issues
• 官方文档: https://docs.kesi.link