玄道智控平台

# 服务插件

文档版本 内容修订 修订人 修订日期
V1.0 添加使用手册基本内容 王垚 2023-11-25

# 快速开始

服务插件是为中控提供功能扩展的一种技术方案，可以在不重启中控的基础上为其添加功能扩展。 通过加载不同类型的插件进行组合，满足不同场景的使用需求，例如：会议室、体育场、指挥中心、展厅等。

服务插件开发底层技术不限制底层开发技术方案，你可以选择任意你习惯的开发语言，已经经过验证可行的语言包括 NodeJS、Go、Java、Python、C/C++ 等。需要注意的是，服务插件不适合带有 GUI 的程序，仅适用于一些对外提供接口的程序，提供的接口和协议类型不限，可以选择 HTTP、TCP、UDP、Modbus、MQTT 等作为接口，如果是 B/S 架构的程序，可以在程序中同时提供网页服务。

⚠️注意：

  1. 开始之前请先准备好对应语言的开发工具，如 VSCode、WebStorm、GoLand、IDEA 等，根据自己的编程习惯进行选择。
  2. 开发平台可以选择适合的平台，例如 Windows、Linux、MacOS 均可，不受限制。
  3. 如果你想要让你开发的插件运行在更多的平台上，请选择一款合适的支持跨平台构建的语言。

# 安装服务管理

  1. 到 通用中控 (opens new window) 中选择合适平台的 SansiDaemon 进行下载。
  2. 根据 部署手册 安装服务管理。

# 项目构建

根据项目的需求选择合适的语言构建项目，确保项目可以直接在目标平台的设备上运行，如果是跨平台构建，如在 windows 上构建 linux 程序，请确保编程语言本身具有跨平台特性，并准备好跨平台构建的工具链。

将程序先编译为目标产物，如 TS 构建为 js，Java 构建为 jar，Go 构建为二进制可执行文件，并直接将程序在目标设备上进行运行，确定运行正常。

# 描述文件

准备一个类似于下面的描述文件。

# ⚠️注意：以下仅为最基础的插件描述信息，如果需要更详细的内容，例如: 声明可配置文件，声明更新忽略项，声明接口信息等，请参考 服务插件-插件规范

跨平台语言的描述信息：

{
  "interpreter": "node",
  "path": "./app.js",
  "pkg": "com.sansi.demo",
  "version": "1.0.0",
  "icon": "icon.png",
  "name": "测试程序",
  "description": "描述信息", 
  "port": 8888,
  "port_type": "HTTP",
  "homepage": "http://{{currentIp}}:{{currentPort}}",
  "os": "",
  "arch": ""
}

非跨平台语言的描述信息：

{
  "interpreter": "",
  "path": "./app",
  "pkg": "com.sansi.demo",
  "version": "1.0.0",
  "icon": "icon.png",
  "name": "测试程序",
  "description": "描述信息", 
  "port": 8888,
  "port_type": "HTTP",
  "homepage": "http://{{currentIp}}:{{currentPort}}",
  "os": "linux",
  "arch": "amd64"
}

# 打包程序

假设我们存在一个 nodejs 程序，它的目录结构如下：

├── app.js      (主程序)
├── daemon.json (描述文件)
└── icon.png    (项目图标)

image-20231125021407445

app.js

const http = require('http');

const server = http.createServer((req, res) => {
  res.statusCode = 200;
  res.setHeader('Content-Type', 'text/plain');
  res.end('Hello World\n');
});

const PORT = 8888;
server.listen(PORT, () => {
  console.log(`服务器运行在 http://localhost:${PORT}/`);
});

daemon.json

{
  "interpreter": "node",
  "path": "./app.js",
  "pkg": "com.sansi.demo",
  "version": "1.0.0",
  "icon": "icon.png",
  "name": "测试程序",
  "description": "描述信息", 
  "port": 8888,
  "port_type": "HTTP",
  "homepage": "http://{{currentIp}}:{{currentPort}}",
  "os": "",
  "arch": ""
}

将程序和描述文件放在一起，并打包压缩，使用 zip 格式，并将文件后缀名修改为 msvc。

image-20231125023406879

image-20231125023438053

之后将文件上传到服务管理，上传后即可看到该服务。

image-20231125024107146

# ⚠️注意

在压缩文件时需要将 daemon.json 文件放在压缩文件根目录，压缩文件中不要带文件夹，一种典型的错误形式如下，压缩文件中包括了一个目录，daemon.json 不在根目录下。

image-20231125161605365

image-20231125161844777

# 发布插件

发布后的插件会存放在三思配置平台上，可以在插件仓库中进行下载和更新。

# 本地发布

  1. 安装 node，建议版本号在 18 以上，安装完成后使用 node -v 命令进行确认。

  2. 安装发布工具，运行命令 npm install spub -g 安装插件发布工具，如果你不使用 npm，使用 yarn、cnpm 均可。

  3. 在三思云平台 (opens new window)上申请发布用到 token。

  4. 在环境变量中添加 SANSI_CLOUD_PLUGIN_TOKEN 这个环境变量，值为申请到的 token 字符串。

  5. 运行 spub -f xxxx.msvc --open 可以将插件发布到云平台上。

# CI 发布

  1. 在云平台上申请发布用到 token。
  2. 在 gitlab 仓库的环境变量中添加 SANSI_CLOUD_PLUGIN_TOKEN 这个环境变量，值为申请到的 token 字符串。
  3. 在 CI 流程中完成程序的编译构建，通过脚本自动化打包为 .msvc 文件。
  4. 在 CI 流程中添加 spub -f xxxx.msvc --open 进行发布。

⚠️注意： --open 表示公开发布。 取消 --open 参数 spub -f xxx，或者声明关闭 spub -f xxx --open false 均表示该版本不公开发布。 非公开发布的版本，不可以在中控在线插件中直接搜索到，需要登录云平台进行查看下载或者通过分享链接进行下载，之后通过本地进行加载。

申请 Token

配置 CI 变量

插件规范 →