diff --git a/docs/message0305.md b/docs/message0305.md new file mode 100644 index 0000000..e68f47e --- /dev/null +++ b/docs/message0305.md @@ -0,0 +1,233 @@ +# 交互流程数据格式说明 + +## register +register的时候,设备端向`server.register`发送注册信息,该信息格式如下: + +```json +{ + "c_id": "client_id", + "r": "该客户端自己生成的公钥", + "m": $object, +} +``` + +其中,`c_id`代表客户端本身的id,用于唯一标识一个客户端,`r`表示客户端自身的公钥,该公钥用于与服务端交换aes密钥。 + +`m`是设备端的一些固有属性,目前结构如下: + +```json +{ + "cpu_core": 4, // 设备cpu核心数 + "memory": 1024, // 内存数,MB + "disk": 1024, // 硬盘容量,GB + "boot_time": 2000, // 启动时间 + "efka_version": "1.0.0", // 客户端版本 + "kernel_arch": "arm64", // 客户端硬件架构 + "province": "", // 所在省 + "city": "", // 所在市 + "adcode": 100, // 所在城市的编号 + "IPv4 1": "ip地址1", + "IPv4 2": "ip地址2", + ... +} +``` + +在服务端,在第一次收到该设备端的注册请求之后,会先将该信息保存下来,当用户在操作界面上对该设备进行授权之后,服务端会生成一个AES密钥,用该设备端的公钥进行加密,然后向`client.auth.$clientid`写入授权信息,客户端收到之后,可以得到本身的授权情况。服务端用RSA公钥加密的结构如下: + +```json +{ + "a": true/false, // 表示是授权还是拒绝授权 + "aes": "", // 如果a字段为true,表示服务端允许授权,该aes为一个加密字符串,以后的通信,服务端和设备端都使用该aes密钥进行加解密。 + "reply": "client.reply.$uuid" // 服务端设置的一个客户端回复的topic,如果服务端在5秒之内没有回复,就认为这个动作失败,服务端就会反馈给操作界面的用户。 +} +``` + +## 数据上传结构 +设备端在采集到数据之后,会向`server.data`发送消息,消息格式如下: + +```json +{ + "c_id": "设备端ID", + "d": $bytes +} +``` + +其中`c_id`是自身的`clientid`,`d`代表具体的采集信息,这部分数据通过与服务端交互商量的aes加密,加密之前是一个列表,列表里面的数据格式如下: + +```json: +[ + { + "client_id": "设备端ID", + "service_name": "从该设备端的哪个服务采集的数据", + "time": $time, // 采集时间,unixnano的int64 + // 该微服务采集的数据,是一个包含map的列表类型,map的内容可以由微服务自己指定 + // 目前一般的格式是"metric-name": $value样式的数据 + "data": [ + { + "name1": "test" + "name2": 124, + "name3": false + } + ], + // 微服务自身可以生成tag,用于微服务指定自己的一些性质,目前使用得不多,以后可以扩展, + // 是一个map[string]string类型的数据 + "tag": { + "tag1": "value1", + "tag2", "value2" + } + } +] +``` + +## 命令下发结构 +命令下发,用于服务端或者其他的系统,通过调用接口,向设备端发送消息,设备端会监听`clients.cmd.$id`的消息。 + +服务端在发送之前,应先用该客户端的aes密钥进行加密,将加密之后的二进制数据发送到该topic。 + +加密前的消息结构如下: + +```json +{ + // 消息类型,目前支持四种消息类型: + // 1代表参数下发,就是向该设备端的微服务发送消息,该消息会辗转发送给微服务进行处理,比如,设置modbus微服务的波特率等消息 + // 2代表采集向下发,比如,设置某个设备短上的modbus微服务采集某个地址的数据 + // 3代表下发微服务文件。 + // 4代表下发数据流图,这个指令用于设置设备端上各个微服务之间的逐句流转。 + "t": 1|2|3|4, + // 针对不同的命令类型,这个字段里的`to`和`m`数据有所不同,具体在下面的小节描述 + "b": { + // 任务id,服务端在下发数据的时候,需要生成一个唯一的uuid, + // 用于标识一个任务 + "t_id": "任务id", + // 表示发给哪个微服务,这里是服务的标识,即服务名称 + "to": "", + // 命令执行的超时时间,单位为秒 + "t": 10, + // 实际内容 + "m": $bytes + } +} +``` + +下面介绍几种下发类型: + +### 参数下发的结构 +对于参数下发,下发内容中的m为一个`map[string]interface{}`结构,用于向某个微服务发送参数,具体参数内容由微服务的参数配置提供。 + +### 采集项下发的结构 +采集项下发时,下发内容中的m为一个`[]map[string]interface{}`结构的列表,每一个条目是一个采集项内容,具体采集向内容由微服务的采集项配置提供。 + + +### 微服务下发的结构 +在微服务下发中,`to`字段会被忽略,可以填写空字符串,而m字段为json化之后的数据,json化之前结构如下: + +```json +{ + "f": "微服务名", + "v": "微服务版本" + "k": "微服务下载的token" + "md5": "微服务的md5值,用于验证下载完整性" + // ms表示是微服务,config表示配置文件,self表示efka的新版本 + "t": "ms|config|self" + // o代表oldversion,老版本,如果t为ms,且o不为空字符串, + // 则表示要升级微服务版本,老版本的内容会被删除和替换。 + "o": "old-version" + +} +``` + +## ping结构 +ping结构会上传到"server.ping", 结构体由msgpack格式编码, ping结构每隔20秒发送一次 + +```json +{ + "c": "client_id", + // 这个ping上传的时间 + "at": $int64, + // 硬件信息,目前有剩余内存,剩余磁盘和cpu负载 + "h": { + // 剩余内存,单位为MB + "fm": $int + // 剩余磁盘,单位为MB + "fd": $int, + // cpu负载,是一个浮点数 + "cp": $float + } +} +``` + +## 命令下发步骤上报结构 +在任务下发之后,设备端会根据命令到哪个环节,进行步骤上报,上报的消息写入到`server.step.feedback`,上报结构如下: + +```json +{ + "c_id": "设备端id", + "d": "aes加密后的二进制数据" +} +``` + +其中,`d`是具体数据经过aes加密后的二进制数据,加密前的结构如下: + +```json +{ + "t_id": "任务的task id", + + // sc为step code,具体地: + // 0代表该任务开始了,服务端创建该任务之后,是这个代码 + // 1代表任务被分发了,服务端向nats(mqtt)发送消息之后,是这个代码 + // 2代表任务被设备端接收到了 + // 3代表该任务已经被发送给微服务进行处理了 + // 4代表该任务已经被微服务收到了,微服务正在处理 + // 5代表任务已经完成,微服务已经处理完成。 + "sc": $int +} +``` + +有了这个步骤,最后任务超时等情况,就可以知道任务卡在哪里。 + +## 命令下发结果上报结构 +任务在微服务处理完成之后,设备端会向服务端反馈任务执行的结果。该结果会写入`server.result.feedback`,上报的结构如下: + +```json +{ + "c_id": "设备端id", + "d": "aes加密后的二进制数据" +} +``` + +其中,`d`是aes加密后的二进制数据,加密前的结构如下: + +```json +{ + "t_id": "任务id", + // unix nano类型 + "t": $int, + // 返回的结果码,0代表成功,其他代表出错 + "c": $int, + "r": "任务执行的结果", + "e": "错误消息,当c为非0时,这个字段会表示出错消息", + // 返回任务类型,1表示任务是微服务下发,0代表是命令下发 + "t": 0 | 1, +} +``` + +## inform结构 +inform用于客户端主动通知服务端本地事情的发生,比如,自身的某个微服务下线了,就会发送一个inform信息给服务端。 + +inform信息会发送给``, 结构如下: + +```json +{ + "c": "client_id", + // 这个inform上传的时间 + "at": $int64, + // 微服务信息 + "s": [{ + "n": "微服务名称", + "v": "微服务版本", + "c": "微服务副本", + // 微服务是否在线,0表示离线,1表示在线 + "s": 0|1 + }] +} +```