开发接口：网关 API 文档
本页汇总 GatewayRuntime、Studio 和 Watchdog 常用接口。调用接口前请先完成登录，并在请求中携带有效 Token（登录后拿到的访问凭证）。
阅读对象
本页不是普通最终用户的主阅读路径，而是系统集成和二次开发参考，用于上位机、MES、SCADA、云平台或自研程序对接。现场电气工程师日常配置和排障通常不需要从 API 开始；采集、调试、数据转发和报警处理请优先阅读对应操作手册。
安全边界
写入变量、重启运行时、修改网络、调整权限、导入配置等接口会影响现场系统。对接程序上线前，应在测试环境验证权限、参数、错误处理和重试策略，并为生产账号分配最小必要权限。
接口术语对照
| 术语 | 现场理解 |
|---|---|
| Token | 登录后拿到的访问凭证，外部系统每次调用接口时都要携带。 |
| 写入变量 | 外部系统或页面向点位下发值，等同于现场常说的“反写点位”。 |
| 目标变量属性 | 某个转发目标对单个变量的外部映射，例如外部字段名、Modbus 从站地址、采样策略或写入权限。 |
| 转发组变量 | 某个数据转发组里实际包含哪些变量。手动选择范围下，变量先加入转发组，后面的目标变量属性才会生效。 |
| Topic | MQTT、Kafka 等消息系统中的主题/路径，外部系统按这个名称接收或订阅数据。 |
基础约定
| 项目 | 说明 |
|---|---|
| GatewayRuntime 默认地址 | http://<网关IP>:6100 |
| Studio 默认地址 | http://<StudioIP>:5100 |
| Watchdog 默认地址 | http://<网关IP>:6200 |
| 数据格式 | 普通接口使用 JSON；文件导入、上传和导出接口使用表单文件或文件流。 |
| 认证方式 | 登录后使用 Bearer Token；未授权或 Token 失效时需要重新登录。 |
| 返回结果 | 接口通常返回统一结果结构，调用方应根据状态码和消息判断是否成功。 |
Studio 和 Watchdog 默认监听 0.0.0.0，当前版本允许客户端通过普通 http://IP:端口 调用。使用普通 HTTP 时必须启用远程管理和 AllowInsecureRemoteHttp；Watchdog 的项目部署与进程控制还必须启用 RemoteDeploymentEnabled。
Studio 与 Watchdog 密码挑战协议
Studio 和 Watchdog 的登录、首次初始化密码不直接放入 JSON 请求。客户端必须按以下当前协议调用：
- 调用对应的密码公钥端点，获取
keyId、publicKey、algorithm、nonce和expiresAt。 - 确认
algorithm等于RSA-OAEP-SHA256。 - 使用
publicKey中的 RSA 2048 SubjectPublicKeyInfo DER Base64 公钥，加密以下 UTF-8 JSON。字段名大小写固定。
{
"Password": "实际密码",
"Nonce": "公钥响应中的nonce"
}
- 将 RSA-OAEP-SHA256 密文进行 Base64 编码，作为登录或初始化请求的
password；同时把keyId作为passwordKeyId提交。 - 登录成功后，后续受保护请求统一发送
Authorization: Bearer <token>。
公钥挑战两分钟过期且只能消费一次。服务端无论解密成功或失败都会使该挑战失效；失败重试必须重新获取公钥。当前协议不接受 Basic Authentication、明文登录密码、RSA-OAEP-SHA1 或旧请求字段作为回退。
浏览器客户端可以在普通 HTTP IP 页面中使用 node-forge 执行 RSA-OAEP-SHA256，并使用 crypto.getRandomValues 生成 OAEP 随机种子；不要依赖该场景通常不可用的 crypto.subtle.importKey。
HTTP 安全边界
一次性 RSA 挑战只额外保护登录和首次初始化的密码字段，不能替代 TLS。Bearer Token、初始化令牌、修改密码请求、工程包、备份和其他业务数据在普通 HTTP 链路上仍没有传输加密。公网或不可信网络应使用 HTTPS。
GatewayRuntime 认证接口
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/auth/GetLoginPasswordPublicKey | 获取登录密码加密公钥 |
| POST | /api/auth/Login | 用户登录 |
| POST | /api/auth/RefreshToken | 刷新 Token |
| POST | /api/auth/ChangePassword | 修改当前用户密码 |
| POST | /api/auth/Logout | 注销当前会话 |
| POST | /api/auth/LogoutAll | 注销当前用户全部会话 |
| POST | /api/auth/Me | 获取当前用户信息 |
| POST | /api/auth/GetMyMenus | 获取当前用户可访问菜单 |
| POST | /api/auth/GetUserPermissions | 获取当前用户权限 |
| GET | /api/auth/GetOAuth2Providers | 获取 OAuth2 提供者 |
| GET | /api/auth/GetRuntimeConfig | 获取登录页运行时配置 |
| POST | /api/auth/OAuth2Exchange | OAuth2 授权码交换 |
| POST | /api/auth/OAuth2Link | 绑定 OAuth2 账号 |
| POST | /api/auth/OAuth2Unlink | 解绑 OAuth2 账号 |
| POST | /api/auth/GetOAuth2Accounts | 获取已绑定 OAuth2 账号 |
GatewayRuntime 总览与元数据
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/gatewayoverviewcontroller/getgatewaytotal | 获取通道、设备、变量、报警统计 |
| GET | /api/gatewayoverviewcontroller/getcollectdevices | 获取采集设备概览 |
| GET | /api/gatewayoverviewcontroller/getchanneldevice | 按设备获取所属通道和设备摘要 |
| GET | /api/gatewayoverviewcontroller/getofflinedevices | 获取离线设备列表 |
| POST | /api/gatewayoverviewcontroller/inserttestdata、inserttestdtudata | 生成演示采集数据或 DTU 演示数据 |
| POST | /api/gatewayoverviewcontroller/getchannelstatuspagelist | 分页获取通道状态 |
| POST | /api/gatewayoverviewcontroller/getdevicestatuspagelist | 分页获取设备状态 |
| POST | /api/gatewayoverviewcontroller/getvariablestatuspagelist | 分页获取变量状态 |
| GET | /api/gatewaysystemcontroller/getsysteminfo | 获取 CPU、内存、磁盘、运行时等系统信息 |
| GET | /api/gatewayprojectcontroller/getprojectinfo | 获取当前工程信息 |
| GET | /api/gatewaymetadatacontroller/getpluginlist | 获取采集插件列表 |
| GET | /api/gatewaymetadatacontroller/getdataforwardpluginlist | 获取数据转发插件列表 |
| GET | /api/gatewaymetadatacontroller/getchanneltypes?pluginName=<采集插件完整名> | 获取采集插件支持的通道类型；设备编辑页据此判断“所属通道”是否必填 |
| GET | /api/gatewaymetadatacontroller/getchannelselectlist | 获取通道下拉列表 |
| GET | /api/gatewaymetadatacontroller/getdeviceselectlist | 获取设备下拉列表 |
| GET | /api/gatewaymetadatacontroller/getvariableselectlist | 获取变量下拉列表 |
| GET | /api/gatewaymetadatacontroller/getdatatypes、getdriverpropertyinfo、getaddressdescription | 获取采集插件数据类型、属性定义和地址说明 |
| GET | /api/gatewaymetadatacontroller/getdataforwardtargetpropertyinfo、getdataforwardvariablepropertyinfo | 获取数据转发目标属性和目标变量属性定义 |
采集配置接口
| 对象 | 主要路径 | 用途 |
|---|---|---|
| 通道 | /api/channelcontroller/addchannel、updatechannel、deletechannel、batcheditchannel、copychannel | 通道新增、编辑、删除、批量编辑、复制 |
| 通道导入导出 | /api/channelcontroller/channelexcelexport、channelpageexcelexport、channelexcelimport | 通道 Excel 导入导出 |
| 设备 | /api/devicecontroller/adddevice、updatedevice、deletedevice、batcheditdevice、copydevice | 设备新增、编辑、删除、批量编辑、复制 |
| 设备导入导出 | /api/devicecontroller/deviceexcelexport、devicepageexcelexport、deviceexcelimport | 设备 Excel 导入导出 |
| 变量 | /api/variablecontroller/addvariable、updatevariable、deletevariable、batcheditvariable、copyvariable | 变量新增、编辑、删除、批量编辑、复制 |
| 变量导入导出 | /api/variablecontroller/variableexcelexport、variableexcelimport、gatewaydataexcelexport、gatewaydataexcelimport | 变量和网关配置导入导出 |
| 写入变量 | /api/gatewaywritevariablecontroller/setvariablevalue | 写入变量值 |
数据转发接口
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /api/gatewaydataforwardcontroller/getgroups | 获取转发组 |
| GET | /api/gatewaydataforwardcontroller/gettargets | 获取转发目标 |
| GET | /api/gatewaydataforwardcontroller/getgroupvariables | 获取转发组变量 |
| GET | /api/gatewaydataforwardcontroller/gettargetvariableproperties | 获取目标变量属性 |
| GET | /api/gatewaydataforwardcontroller/getruntime | 获取数据转发运行状态 |
| POST | /api/gatewaydataforwardcontroller/addgroup、updategroup、deletegroup、restartgroup | 转发组维护 |
| POST | /api/gatewaydataforwardcontroller/addtarget、updatetarget、deletetarget、restarttarget | 转发目标维护 |
| POST | /api/gatewaydataforwardcontroller/switchtargetredundant | 手动切换转发目标冗余状态 |
| POST | /api/gatewaydataforwardcontroller/setgroupvariables | 保存转发组变量 |
| POST | /api/gatewaydataforwardcontroller/upserttargetvariableproperty、deletetargetvariableproperty | 保存或删除目标变量属性 |
| POST | /api/gatewaydataforwardcontroller/getgrouplog、gettargetlog | 查询转发运行日志 |
| POST | /api/gatewaydataforwardcontroller/updategrouploglevel、updatetargetloglevel | 调整转发组或转发目标日志级别 |
| POST | /api/gatewaydataforwardcontroller/exportgrouplog、exporttargetlog | 导出转发运行日志 |
| POST | /api/gatewaydataforwardcontroller/dataforwardexcelexport、dataforwardexcelimport | 数据转发配置导入导出 |
数据转发接口中，转发组变量关系决定变量是否属于某个转发组；目标变量属性只描述某个目标如何使用该变量。手动选择范围下，保存目标变量属性前应先通过 setgroupvariables 把变量加入转发组。
数据查询与实时报警接口
| 方法 | 路径 | 用途 |
|---|---|---|
| POST | /api/gatewayrealdatacontroller/GetRealDataRecordsByTarget | 查询实时数据记录 |
| GET | /api/gatewayrealdatacontroller/GetRealDataTargetNames | 获取实时数据目标 |
| POST | /api/gatewayrealdatacontroller/ExportRealDataRecords | 导出实时数据记录 |
| POST | /api/gatewayhisdatacontroller/GetHisDataRecordsByTarget | 查询历史数据记录 |
| POST | /api/gatewayhisdatacontroller/GetHisNumberDataRecordsByTarget | 查询历史数值数据 |
| POST | /api/gatewayhisdatacontroller/GetTypedHisDataRecordsByTarget、GetTypedHisNumberDataRecordsByTarget | 按 UTC 时间范围、变量集合、分页和白名单排序查询类型化历史记录 |
| POST | /api/gatewayhisdatacontroller/GetHisNumberSeriesByTarget | 查询 Auto、Raw、Average、Minimum、Maximum、First、Last 等模式的历史数值序列 |
| GET | /api/gatewayhisdatacontroller/GetHisDataTargetNames | 获取历史数据目标 |
| POST | /api/gatewayhisdatacontroller/ExportHisDataRecords、ExportHisNumberDataRecords | 导出历史字符串或数值数据 |
| POST | /api/customsqldatacontroller/GetCustomSqlDataByTarget | 查询自定义 SQL 历史数据 |
| GET | /api/customsqldatacontroller/GetCustomSqlColumns | 获取自定义 SQL 列 |
| POST | /api/customsqldatacontroller/ExportCustomSqlData | 导出自定义 SQL 数据 |
| POST | /api/gatewayrealalarmcontroller/getrealalarmvariables | 查询实时报警 |
| POST | /api/gatewayrealalarmcontroller/confirmalarm | 确认实时报警 |
| POST | /api/gatewayhisalarmcontroller/GetHisAlarmRecordsByTarget | 查询历史报警 |
| GET | /api/gatewayhisalarmcontroller/GetHisAlarmTargetNames | 获取历史报警目标 |
| POST | /api/gatewayhisalarmcontroller/ExportHisAlarmRecords | 导出历史报警 |
类型化历史查询应使用 UTC 起止时间，并受变量数、时间跨度、分页大小、序列点数、源记录数和导出行数上限保护。默认上限在 Configuration/HisDataQueryOptions.json 中维护；集成方应按分页和数值序列聚合能力设计请求，不要通过超大时间范围一次拉取全部原始记录。
MQTT 客户端和 MQTT 服务端生产者还可通过默认主题 RpcHistory 调用同一组历史能力：请求主题为 RpcHistory/<32位十六进制请求号>，响应主题为 RpcHistory/<请求号>/Response。协议支持目标、记录、数值序列、历史报警、确认报警和取消请求；大响应使用 gzip 后 Base64 分块，并受请求体、响应体、分块大小、并发数和超时限制。
设备与转发目标调试接口
| 模块 | 主要路径 | 用途 |
|---|---|---|
| 调试对象 | /api/debugController/getsubject、canhandle | 获取采集设备或转发目标的调试对象和能力 |
| 基础读写 | /api/debugController/read、write、batchread、batchwrite | Foundation 类设备地址读写和批量读写 |
| TCP 服务端 | /api/debugController/gettcpclients、kicktcpclient | 查看或踢出 TCP 服务端客户端 |
| OPC UA | /api/opcUaController/browse、readnode、writenode、subscribe、unsubscribe、getsubscriptions、readnodeattribute、exportvariables、importtodatabase | OPC UA 节点浏览、读写、订阅和变量导入导出 |
| OPC DA | /api/opcDaController/browse、readnode、writenode、subscribe、unsubscribe、getsubscriptions、exportvariables、importtodatabase | OPC DA 节点浏览、读写、订阅和变量导入导出 |
| MQTT Client | /api/mqttClientController/publish、subscribe、unsubscribe、getsubscriptions | MQTT 客户端发布、订阅和订阅列表 |
| MQTT Server | /api/mqttserverController/getclients、getstats、kickclient、publish | MQTT 服务端客户端、Topic 统计、踢出客户端和发布测试 |
| Kafka / RabbitMQ | /api/kafkaController/publish、/api/rabbitmqController/publish | Kafka Topic 或 RabbitMQ Routing Key 发布测试 |
| CAN / ZeroMQ | /api/canController/sendFrame、readFrame、/api/zeroMQController/publish | CAN 帧收发和 ZeroMQ 发布测试 |
| IEC61850 Client | /api/iec61850Controller/GetLogicalDeviceList、GetDataDirectory、ReadValue、WriteValue、BrowseModel、GetConnectionStatus、GetLogicalNodeDirectory、GetReportSubscriptionStatus、GetGooseSubscriptionStatus、ReadDataSet、GetDataSetDirectory、GetControlModel、ControlOperate | IEC61850 客户端模型浏览、读写、报告/GOOSE 状态和控制操作 |
| IEC61850 Server | /api/iec61850ServerController/GetLogicalDeviceList、GetDataModelTree、BrowseModel、GetConnectionCount、GetConnectedClients、ReadAttributeValue、WriteAttributeValue、GetServerStatus、GetVariableMapStats | IEC61850 服务端模型、客户端连接和变量映射调试 |
| SOE 事件 | /api/soeEventController/GetProviderNames、GetSoeEventRecords、ExportSoeEventRecords | 查询和导出 SOE 事件记录 |
规则、脚本、节点接口
| 模块 | 主要路径 | 用途 |
|---|---|---|
| 规则流程 | /api/gatewayruleenginecontroller/getruleflowspaged、saveruleflow、deleteruleflows、toggleflowenabled | 规则流程查询、保存、删除、启停 |
| 规则运行 | /api/gatewayruleenginecontroller/getruleenginestatus、getallflownodevalues、getruleenginelog | 规则运行状态、节点值、日志 |
| 规则导入导出 | /api/gatewayruleenginecontroller/ruleflowexcelexport、ruleflowexcelimport | 规则 Excel 导入导出 |
| 脚本 | /api/gatewayscriptcontroller/getscriptlist、createscript、deletescripts、compilescript、compileallscripts | 脚本列表、创建、删除、编译 |
| 脚本元数据 | /api/gatewayscriptcontroller/getregisteredexpressionspaged、getexpressioncategories、getscriptcategories | 已注册表达式、分类 |
| 自定义节点 | /api/gatewaycustomnodecontroller/getcustomnodespaged、createcustomnode、deletecustomnodes、compileallcustomnodes | 自定义节点列表、创建、删除、批量编译 |
| 编辑器辅助 | /api/completion/complete、codecheck、signaturehelp、hover、definition、formatcode | 脚本和节点编辑器代码提示、检查和格式化 |
插件、证书和系统设置接口
| 模块 | 主要路径 | 用途 |
|---|---|---|
| 插件 | /api/gatewayplugincontroller/getplugins、updatepluginenable、batchenableplugins、batchdisableplugins、syncpluginconfigs | 插件列表、启停、同步 |
| 证书 | /api/certificatecontroller/getcertificates、addcertificate、updatecertificate、deletecertificates、generatecertificateauthority、generateservercertificate、generateclientcertificate、exportcertificate、exportprivatecertificate、getcertificateselectlist | TAdmin 统一证书查询、上传、更新、删除、生成、导出和下拉选择 |
| 报警配置 | /api/gatewayalarmconfigcontroller/GetAlarmConfig、UpdateAlarmConfig | 报警恢复策略 |
| 冗余 | /api/gatewayredundantcontroller/getsitecollectstate、GetSiteDataForwardState、getredundancyoptions、setredundancyoptions、switchredundantstate | 网关采集/转发状态、主备冗余配置和状态切换 |
| 网络 | /api/gatewaynetworkconfigcontroller/getnetworkconfigs、setnetworkconfig | 网卡配置查询与设置 |
| 时间同步 | /api/gatewaytimecontroller/getsystemtime、setsystemtime、getntpconfig、setntpconfig、syncntptime | 系统时间和 NTP 配置 |
| 系统控制 | /api/gatewayrestartcontroller/restartgateway、restartruntime、restartapplication | 重启网关、运行时或应用 |
| 备份 | /api/backupcontroller/backupconfigdatabase | 备份配置数据库 |
| PING | /api/gatewaypingcontroller/pingtest | 网络连通性测试 |
证书接口升级
证书管理已迁移到 TAdmin 统一模块。旧 /api/gatewaycertificatecontroller/... 控制器不再是当前接口；调用方必须改用 /api/certificatecontroller/...，同步调整 generatecertificateauthority、deletecertificates 等动作名称以及 certificate:* 权限码。
日志接口
| 日志类型 | 主要路径 |
|---|---|
| 后台日志 | /api/backendlogcontroller/getbackendlog、getbackendlogsources、getallbackendlog、exportbackendlog、exportallbackendlog |
| 通道日志 | /api/channelcontroller/getchannellog、updatechannelloglevel、exportchannellog |
| 设备日志 | /api/devicecontroller/getdevicelog、updatedeviceloglevel、exportdevicelog |
| 操作日志 | /api/adminsystemlogcontroller/getoperatelog、/api/adminsystemlogcontroller/exportoperatelog |
| RPC 日志 | /api/rpclogcontroller/getrpclog、exportrpclog |
| SQL 日志 | /api/adminsystemlogcontroller/getsqllog、/api/adminsystemlogcontroller/exportsqllog |
| 审计日志 | /api/adminauditlogcontroller/getloginaudit、getpermissionaudit、getusersecurityaudit 及对应导出接口 |
管理权限接口
| 对象 | 主要路径 | 用途 |
|---|---|---|
| 用户 | /api/gatewayusercontroller/getusers、adduser、updateuser、setroles、resetpassword、lock、unlock、deleteuser | 用户生命周期和角色分配 |
| 会话 | /api/gatewayusercontroller/getusersessions、revokesession、setsessionrevoked | 用户会话管理 |
| 角色 | /api/gatewayrolecontroller/getroles、addrole、updaterole、copyrole、setpermissions、previewpermissiondiff、getpermissioncatalog、getallapimethods、getallbuttons、getrolebyid、deleterole | 角色和权限维护 |
| 菜单 | /api/gatewaymenucontroller/getmenutree、savemenu、validatemenu、movemenu、setmenuenabled、setmenuvisible、deletemenu | 菜单树维护 |
| 按钮 | /api/gatewaybuttoncontroller/getbuttons、getbuttonsbymenuid、getallbuttons、addbutton、updatebutton、deletebutton | 按钮权限维护 |
Studio 与 Watchdog 接口
Studio 认证
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/auth/GetLoginPasswordPublicKey | 获取两分钟有效的一次性 RSA-OAEP-SHA256 密码挑战。 |
GET | /api/auth/BootstrapStatus | 查询是否需要首次管理员初始化。 |
POST | /api/auth/Bootstrap | 使用 token、passwordKeyId、密码 Base64 密文 password 初始化管理员。 |
POST | /api/auth/Login | 使用 name、passwordKeyId、密码 Base64 密文 password 登录。 |
POST | /api/auth/ChangePassword | 使用 Studio JWT Bearer 修改当前密码，并返回重新签发的 JWT。 |
Studio 登录成功后返回七天有效的 JWT Bearer。首次初始化令牌位于运行目录 Data/studio_bootstrap.token，初始化成功后删除；初始化允许来自已启用远程管理的 IP 地址。
Watchdog 认证
| 方法 | 路径 | 说明 |
|---|---|---|
GET | /api/watchdog/login/password-public-key | 获取两分钟有效的一次性 RSA-OAEP-SHA256 密码挑战。 |
GET | /api/watchdog/bootstrap/status | 查询是否需要首次管理员初始化。 |
POST | /api/watchdog/bootstrap | 使用 token、passwordKeyId、密码 Base64 密文 password 初始化管理员。 |
POST | /api/watchdog/login | 使用 username、passwordKeyId、密码 Base64 密文 password 登录。 |
POST | /api/watchdog/logout | 撤销当前 Bearer 会话。 |
Watchdog 登录成功后返回 accessToken、username 和 expiresAt。Token 是八小时有效的随机不透明值，服务端只在内存中保存 SHA-256 摘要；登出或 Watchdog 重启后失效。首次初始化令牌位于运行目录 Data/watchdog_bootstrap.token，初始化成功后删除。
| 应用 | 主要路径 | 用途 |
|---|---|---|
| Studio 认证 | /api/auth/GetLoginPasswordPublicKey、BootstrapStatus、Bootstrap、Login、ChangePassword | Studio 一次性密码挑战、初始化、登录和改密 |
| Studio 工程 | /api/project/list、create、update、import | 工程列表、创建、编辑、导入 |
| Studio 运行时 | /api/runtime/current-project、start、stop、gateway-version、app-version | 本机运行时状态和版本 |
| Studio 看门狗 | /api/watchdog/configs、config/save、upload、download | 看门狗连接、上传、下载 |
| Studio 隧道 | /api/tunnel/status、listeners、config、start、stop | 隧道代理状态和配置 |
| Watchdog 认证 | /api/watchdog/login/password-public-key、bootstrap/status、bootstrap、login、logout | Watchdog 一次性密码挑战、初始化、Bearer 登录和登出 |
| Watchdog 状态 | /api/watchdog/status、projects、logs、backups | 仪表盘、项目、日志、备份 |
| Watchdog 项目 | /api/watchdog/project/upload、project/download/{name}、apply/{name}、project/{name} | 项目上传、下载、应用、删除 |
| Watchdog 进程 | /api/watchdog/restart、stop | 重启或停止网关运行时 |
| Watchdog 备份 | /api/watchdog/backup/create、backup/restore/{name}、backup/{name} | 创建、恢复、删除备份 |
| Watchdog 隧道 | /api/watchdog/tunnel/status、activate/{name}、deactivate/{name}、activate-all、deactivate-all | 隧道客户端状态和启停 |
| Watchdog 设置 | /api/watchdog/options、change-password | Watchdog 配置和密码修改 |
使用注意
- 接口路径请按表格中的大小写和路径调用。
- 导入导出、上传、下载接口可能返回文件或接收表单文件，请按接口文档中的请求格式调用。
- 管理类接口受菜单、按钮、API 权限共同限制；角色授权不足时，即使 Token 有效也可能返回无权限。