ThingsGatewayRuntime.Foundation 2.2.13

ThingsGatewayRuntime

ThingsGatewayRuntime 是 ThingsGateway 的工业物联网边缘网关运行时，负责设备采集、变量计算、数据转发、历史数据、实时报警、规则引擎和 Web 管理。

项目组成

功能特性

• 通道、设备、变量的统一建模、批量配置、状态监控和在线调试。
• Modbus、Siemens S7、DL/T 645、MQTT、OPC UA/DA 等内置协议，扩展协议由插件项目提供。
• 实时数据缓存、变量读写、WebSocket 推送和网关间同步。
• 历史数据与历史报警查询、实时报警、确认和配置管理。
• 采集驱动与业务插件生命周期、动态属性和权限元数据。
• 数据转发到 MQTT、RabbitMQ、Kafka、数据库、HTTP 等目标。
• 可视化规则流、自定义节点、运行时脚本和表达式。
• 工程备份恢复、冗余管理、健康检查、日志、审计和 TAdmin 权限体系。

历史数据数据库矩阵

历史数据转发与查询覆盖 SQLite、SQL Server、MySQL、PostgreSQL、QuestDB、TDengine 和 IoTDB。当前浏览器验收矩阵包含 22 个相互隔离的目标：8 个普通目标、7 个显式自定义 SQL 目标，以及 7 个开启自定义 SQL但建表、插入、删除模板全部留空的自动生成目标。

数据查询页遵循以下契约：

• 普通模式返回设备名称、变量名称、变量 ID、值、采集时间、在线状态、记录时间、源 Epoch、源序列、源节点和记录键。没有冗余来源元数据时，源节点与记录键为空；其余字段必须有值。
• 通用自定义宽表返回 event_time、main_value、copy_value 和 device_name；IoTDB 自动表额外返回 group_key，IoTDB 显式自定义表返回 time、device_id、variable_id、variable_name、value 和 is_online。
• 普通模式按变量写入记录，两个变量通常每周期产生两行；合并宽表通常每周期产生一行，因此两种模式的累计总数不要求相同。分页栏中的 50条/页 是当前分页大小，总数以“共 N 条”为准。
• 切换查询目标时必须清空上一目标的分页排序字段并重建表格排序状态，不能把普通表的 createTime 排序带入使用 event_time 或 time 的自定义表。
• 普通模式的 IoTDB 与 QuestDB 原生 UTC 时间在服务端按目标配置时区投影为墙钟时间；例如目标配置 +08:00 时，UTC 09:42Z 在普通表显示为 17:42。IoTDB 与 QuestDB 自定义宽表保留原始 Z 后缀，明确表示 UTC。
• QuestDB 普通查询必须应用页面传入的条件和排序；按记录时间降序时使用 CreateTime DESC，不能退回到可能长期不变的 CollectTime。

2026-08-30 使用 Asia/Shanghai 浏览器时区完成 22 个目标的实际 UI 验收：所有目标均返回 50 行；宽表最新行的两个数值均为 42.5、设备名称为 Memory 且没有空字段；普通表除源节点和记录键外字段完整。修复后 IoTDB Table、IoTDB Tree 和 QuestDB Normal 的最新记录时间分别与本地当前时间一致，IoTDB/QuestDB 宽表仍返回带 Z 的 UTC 时间。

技术栈

目录结构

ThingsGatewayRuntime/
|-- analyzer/
|   |-- ThingsGatewayRuntime.ExpressionsGenerator/
|   `-- ThingsGatewayRuntime.PluginsGenerator/
|-- src/
|   |-- Bootstrapper/
|   |-- ThingsGatewayRuntime/
|   |-- ThingsGatewayRuntime.Application/
|   |-- ThingsGatewayRuntime.Foundation/
|   |-- ThingsGatewayRuntime.Frontend/
|   |-- ThingsGatewayRuntime.Plugin/
|   |-- ThingsGatewayRuntime.NOAOTFoundation/
|   |-- ThingsGatewayRuntime.NOAOTPlugin/
|   `-- ThingsGatewayScriptCompiler/
|-- test/ThingsGatewayRuntime.Test/
|-- web/
|-- Directory.Build.props
`-- README.md

开发环境

• .NET SDK 10
• Node.js 22 和 npm
• 仓库工作区构建时使用同级 TAdmin、TUtility 和 TORM 源码；单独使用项目时改用对应 NuGet 包。

构建

从 ThingsGateway 目录构建包含 Runtime、PRO 和 Studio 的解决方案：

dotnet restore ThingsGatewayRuntime.slnx
dotnet build ThingsGatewayRuntime.slnx -c Release

只构建运行时：

dotnet build ThingsGatewayRuntime/src/ThingsGatewayRuntime/ThingsGatewayRuntime.csproj -c Release

运行测试：

dotnet test ThingsGatewayRuntime/test/ThingsGatewayRuntime.Test/ThingsGatewayRuntime.Test.csproj -c Release

前端开发

cd web
npm install
npm run dev

开发服务器默认使用 http://localhost:3100。构建生产资源：

npm run check
npm run build

npm run build 会执行类型检查、生成静态资源，并把资源复制到 ThingsGatewayRuntime.Frontend 的嵌入目录。

运行

先构建前端资源，再启动后端：

dotnet run --project src/ThingsGatewayRuntime/ThingsGatewayRuntime.csproj

默认 WebApi 端口为 6100。运行目录下的 Configuration 用于数据库、JWT、OAuth2、日志、历史查询和 WebApi 配置；默认 SQLite 连接启用 WAL 日志模式。

扩展开发

• 采集插件、业务插件和属性元数据开发参见 插件二次开发。
• 运行时脚本、表达式和自定义节点文档位于 官方文档站点源码。
• Studio 与 Watchdog 的工程开发和部署说明参见 ThingsGatewayStudio。

相关资源

• 官方文档：https://runtime.thingsgateway.cn/
• Gitee：https://gitee.com/diego2098/ThingsGateway
• GitHub：https://github.com/kimdiego2098/ThingsGateway
• QQ 群：605534569

许可证

本项目使用 Apache-2.0 协议。