设备开放接口文档

以下是系统中所有开放接口和协议的详细信息。数据通过接口动态加载。

接口文档
协议列表
协议结构
配置说明
流程图
开放接口列表
加载中...
{{ errorInterfaces }}
{{ category }} {{ getInterfaceCountByCategory(category) }}个接口
{{ item.method }}
{{ item.path }}
{{ item.name }}
{{ expandedInterfaces.includes(item.path + item.name) ? '▲' : '▼' }}

{{ item.description }}

请求示例
{{ JSON.stringify(item.request_example, null, 2) }}
返回示例
{{ JSON.stringify(item.response_example, null, 2) }}
协议详情列表
加载中...
{{ errorProtocols }}
ID: {{ protocol.id }}
{{ protocol.name }} 回调
{{ protocol.read_com ? '读取: ' + protocol.read_com : '-' }}
{{ protocol.write_com ? '写入: ' + protocol.write_com : '-' }}
{{ expandedProtocols.includes(protocol.id) ? '▲' : '▼' }}

{{ protocol.note }}

长度单位为字节。1 字节占 2 位十六进制，取值范围为 00-FF（十进制 0-255，共 256 个取值）；字段占用的十六进制字符数 = 长度 × 2。

协议数据结构

Protocol 结构体

协议主表结构，存储协议的基本信息和配置

字段名 类型 JSON键 GORM标签 说明
ID int id primaryKey;autoIncrement 协议ID，自增主键
CreateTime *time.Time create_time type:datetime 创建时间
UpdateTime *time.Time update_time type:datetime 更新时间
DeleteTime gorm.DeletedAt delete_time index 软删除时间
Name string name type:varchar(255);not null 协议名称
ProtocolData string protocol_data type:json;not null 协议请求数据字段定义(JSON格式)
ResData string res_data type:json;not null 协议响应数据字段定义，如与请求一致可为空
ReadCom string read_com type:varchar(4);not null 读取命令码(COM)
WriteCom string write_com type:varchar(4) 写入命令码(COM)
Note string note type:varchar(255) 协议说明备注
Type int8 type type:tinyint;not null 协议类型: 1=读取协议, 2=写入协议
IsShow int8 is_show type:tinyint;not null;default:1 是否显示: 0=隐藏, 1=显示
Cid string cid type:varchar(4) 设备CID标识
UiData string ui_data type:text UI配置数据
CanMaterial int8 can_material type:tinyint;default:0 是否可用于物料: 0=否, 1=是
BanRoles string ban_roles type:varchar(255) 禁止访问的角色ID列表
Modes string modes type:varchar(20) 支持的设备模式
Version string version type:varchar(20) 协议版本号
IsCache int8 is_cache type:tinyint;default:0 是否缓存: 0=否, 1=是
IsLog int8 is_log type:tinyint;default:1 是否记录日志: 0=否, 1=是(如心跳协议可设为0)
IsCallback int8 is_callback type:tinyint;default:0 是否回调协议: 0=否, 1=是

ProtocolItem 结构体

协议字段项定义，用于描述协议中每个数据字段的属性

字段名 类型 JSON键 说明
Name string name 字段显示名称
Note string note 字段说明/备注
Type string type 字段类型: picker/datetime/range/switch/text/number/wid/card
Field string field 字段标识符(用于数据解析)
Length int length 字段长度，单位为字节。1 字节占 2 位十六进制，范围 00-FF（十进制 0-255，共 256 个取值）
Required int required 是否必填: 0=否, 1=是
Placeholder string placeholder 输入框占位提示文本
Range []ProtocolRange range 选项列表(picker类型使用)
Ext string ext 扩展信息，通常为字段单位
Sign int sign 是否有符号: 0=无符号, 1=有符号
Exchange int exchange 数据转换类型: 0=无, 1=Bin2Dec, 2=Dec2Bin, 3=Oct2Dec, 4=Dec2Oct, 5=Hex2Dec, 6=Hex, 7=Ascii, 8=GB2312
Multiple string multiple 乘数因子
InputType string input_type 输入类型
Max string max 最大值(range类型使用)
Min string min 最小值(range类型使用)
OpenText string openText 开关开启文本(switch类型使用)
CloseText string closeText 开关关闭文本(switch类型使用)
Format string format 日期时间格式(datetime类型使用): hhii/hhiiss/iiss/yyyymmdd/yymmdd/yy/yyyy/mmdd/mm/dd/hh/ii/ss/ww
IsLock bool is_lock 是否锁定
IsSum int is_sum 是否为校验和字段
Float int float 小数位数
Wid int wid 关联的WID
ComList []ProtocolComList comList COM命令列表
Value any value 【数据显示】字段值
ValueHex string value_hex 【数据显示】十六进制值
ValueShow string value_show 【数据显示】显示值

常量定义

协议类型常量

常量名 值 说明
ProtocolTypeRead 1 读取协议类型
ProtocolTypeWrite 2 写入协议类型

字段类型常量

常量名 值 说明
ProtocolItemTypePicker "picker" 选择器类型
ProtocolItemTypeDatetime "datetime" 日期时间类型
ProtocolItemTypeRange "range" 范围滑块类型
ProtocolItemTypeSwitch "switch" 开关类型
ProtocolItemTypeText "text" 文本类型
ProtocolItemTypeNumber "number" 数字类型
ProtocolItemTypeWid "wid" WID类型
ProtocolItemTypeCard "card" 卡片类型

数据转换常量

常量名 值 说明
ProtocolExchangeNone 0 不转换
ProtocolExchangeBin2Dec 1 二进制转十进制
ProtocolExchangeDec2Bin 2 十进制转二进制
ProtocolExchangeOct2Dec 3 八进制转十进制
ProtocolExchangeDec2Oct 4 十进制转八进制
ProtocolExchangeHex2Dec 5 十六进制转十进制
ProtocolExchangeHex 6 十六进制
ProtocolExchangeAscii 7 ASCII编码
ProtocolExchangeGB2312 8 GB2312编码

日期时间格式映射

格式键 格式模板 说明
hhii %s:%s 时:分
hhiiss %s:%s:%s 时:分:秒
iiss %s:%s 分:秒
yyyymmdd %s-%s-%s 年-月-日
yymmdd %s-%s-%s 年(两位)-月-日
yy %s 年(两位)
yyyy %s 年(四位)
mmdd %s-%s 月-日
mm %s 月
dd %s 日
hh %s 时
ii %s 分
ss %s 秒
ww %s 周
YAML 配置文件说明

配置文件路径

默认配置文件路径：./config/settings.dev.yml

可通过命令行参数指定：-c 或 --config

完整配置示例
# 应用配置 application: name: "德锋设备管理平台" # 应用名称 mode: "dev" # 运行模式: dev(开发环境) 或 prod(生产环境) timezone: "Asia/Shanghai" # 时区设置 uploadPath: "./uploads" # 文件上传路径 urlPath: "" # URL路径前缀 apiHost: "http://127.0.0.1:9001" # API主机地址 # 平台标识（重要：授权文件绑定到此标识） cid: "defeng-device-platform" # 平台唯一标识 # 加密WID密钥 wid_keys: "" # WID加密密钥，用于设备唯一码加密 # 管理员配置（生产环境必须修改） admin: username: "admin" # 管理员用户名 password: "admin123" # 管理员密码（生产环境必须改为强密码） # 开放接口配置（生产环境必须修改） openApi: header: "X-Open-Api-Key" # API Key请求头名称 keys: # API Key列表（生产环境必须配置强随机密钥） - dev-open-api-key-change-me # 开发环境弱密钥（生产环境禁用） # 批量写入配置 batch: size: 1000 # 批量写入大小 interval: 5 # 批量写入间隔(秒) # HTTP服务配置 http: enabledp: true # 是否启用HTTP服务 host: "0.0.0.0" # 监听地址 port: 9001 # 监听端口 timeout: 30 # 超时时间(秒) timezone: "Asia/Shanghai" # HTTP服务时区 # TCP服务配置（设备连接核心服务） tcp: enabledp: true # 是否启用TCP服务 host: "0.0.0.0" # TCP监听地址 port: 9999 # TCP监听端口 heartbeat: 30 # 心跳检测时间(秒) # 数据库配置 database: type: "mysql" # 数据库类型 host: "127.0.0.1" # 数据库主机地址 port: 3306 # 数据库端口 user: "root" # 数据库用户名 password: "root" # 数据库密码 dbname: "defeng_device" # 数据库名称 charset: "utf8mb4" # 数据库字符集 maxidleconns: 10 # 最大空闲连接数 maxopenconns: 100 # 最大打开连接数 # Redis配置 redis: host: "127.0.0.1" # Redis主机地址 port: 6379 # Redis端口 password: "" # Redis密码 db: 0 # Redis数据库编号 poolsize: 10 # 连接池大小 # 日志配置 logger: level: "info" # 日志级别: debug/info/warn/error format: "text" # 日志格式: text/json output: "file" # 日志输出: file/console/both filename: "./logs/app.log" # 日志文件路径 maxsize: 10 # 单个日志文件最大大小(MB) maxbackups: 5 # 保留的旧日志文件最大数量 maxage: 30 # 保留旧日志文件的最大天数 # JWT配置 jwt: secret: "your-secret-key-change-me-to-32chars-or-more" # JWT密钥，同时也是授权文件签名密钥（生产环境必须至少32位强随机密钥） expire: 7200 # JWT过期时间(秒)

生产环境安全要求（重要）

当 application.mode 设置为 prod 时，系统会强制验证以下安全配置：

1. 管理员密码安全

项目 要求 禁止 建议
admin.password 必须改为强密码 空密码或弱密码 admin123 至少 12 位，包含大小写字母、数字、特殊字符

2. JWT密钥安全

项目 要求 禁止 说明
jwt.secret 必须至少 32 位强随机密钥 空密钥或弱密钥 123456 此密钥同时用于授权文件签名验证，更换密钥会导致已生成的授权文件失效

3. OpenAPI密钥安全

项目 要求 禁止 建议
openApi.keys 必须配置至少一个强随机 API Key 弱密钥（少于24位或包含 change-me 标识） 每个 API Key 至少 24 位强随机密钥

4. 平台标识（CID）安全

项目 作用 重要性 建议
cid 授权文件服务器绑定，防止授权文件在不同服务器间复制使用 非常重要 每个服务器使用不同的唯一标识

密钥生成方法

使用 OpenSSL 生成强密钥
# 生成32位强随机密钥（用于 jwt.secret） openssl rand -base64 32 # 生成24位强随机密钥（用于 openApi.keys） openssl rand -base64 24 # 生成64位强随机密钥（更安全） openssl rand -base64 64

签名密钥来源

授权文件使用 jwt.secret 作为签名密钥，因此：

影响 说明
更换 jwt.secret 之前生成的授权文件将全部失效
配置建议 建议在生产环境配置后不要随意更改 jwt.secret

生产环境配置示例

生产环境安全配置示例
application: name: "德锋设备管理平台" mode: "prod" # 生产环境模式 timezone: "Asia/Shanghai" uploadPath: "./uploads" urlPath: "" apiHost: "https://your-domain.com" cid: "your-platform-unique-id-12345" # 每个服务器使用不同的唯一标识 admin: username: "admin" password: "StrongPassword@2026!XYZ" # 强密码示例 openApi: header: "X-Open-Api-Key" keys: - "StrongRandomApiKey24charsMore" # 强随机密钥示例 jwt: secret: "StrongJwtSecretKeyAtLeast32CharactersForProductionEnvironment!" # 强密钥示例 expire: 7200 # 其他配置保持不变...

配置验证与错误提示

验证位置

触发条件：当 application.mode == "prod" 时自动验证

错误提示示例

配置不合规时的错误提示
加载配置失败: 生产配置不安全: admin.password必须改为强密码; jwt.secret必须改为至少32位强随机密钥; openApi.keys包含弱API Key

配置影响说明

配置项 更换后影响 建议
jwt.secret 所有已生成的授权文件失效，需要重新生成 生产环境配置后不要随意更改
cid 已生成授权文件签名验证失败，需要重新生成 每个服务器使用固定唯一标识
application.mode 从 dev 切换到 prod 时会强制验证安全配置 确保配置合规后再切换模式
系统流程图

设备通讯流程

设备通讯流程图

设备通讯流程示意图

开放设备流程

开放设备流程图

开放设备流程示意图