产品定价 立即试用
IoT网关
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
文档 > 配置指南 > 常规配置
入门
安装
目录

IoT Gateway配置

目录结构

daemon安装的默认目录结构如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

/etc/thingsboard-gateway/config                   - Configuration folder.
    tb_gateway.json                               - Main configuration file for Gateway.
    logs.json                                     - Configuration file for logging.
    modbus.json                                   - Modbus connector configuration.
    mqtt.json                                     - MQTT connector configuration.
    ble.json                                      - BLE connector configuration.
    opcua.json                                    - OPC-UA connector configuration.
    request.json                                  - Request connector configuration.
    can.json                                      - CAN connector configuration. 
    ... 

/var/lib/thingsboard_gateway/extensions           - Folder for custom connectors/converters.                      
    modbus                                        - Folder for Modbus custom connectors/converters.
    mqtt                                          - Folder for MQTT custom connectors/converters.
        __init__.py                               - Default Python package file, needed for correct imports.
        custom_uplink_mqtt_converter.py           - Custom MQTT converter example.
    ...
    opcua                                         - Folder for OPC-UA custom connectors/converters.
    ble                                           - Folder for BLE custom connectors/converters.
    request                                       - Folder for Request custom connectors/converters.
    can                                           - Folder for CAN custom connectors/converters.

/var/log/thingsboard-gateway                      - Logs folder.
    connector.log                                 - Connector logs.
    service.log                                   - Main gateway service logs.
    storage.log                                   - Storage logs.
    tb_connection.log                             - Logs for connection to the ThingsBoard instance.

环境变量

文档信息图标

环境变量的值优先级高于配置文件中的参数值。 这意味着网关将优先使用环境变量的值（如果已设置）， 而不是配置文件中的值。

网关支持通过环境变量配置关键连接参数。 例如，以下示例展示了如何在Docker Compose文件中通过环境变量配置host、port和access token等基本参数：

1
2
3
4
5
6
7
8
9
10
11
12
13

version: '3.4'
services:
  # ThingsBoard IoT Gateway Service Configuration
  tb-gateway:
    image: thingsboard/tb-gateway
    container_name: tb-gateway
    ...
    # Environment variables
    environment:
      - TB_GW_HOST=host.docker.internal
      - TB_GW_PORT=1883
      - TB_GW_ACCESS_TOKEN=YOUR_ACCESS_TOKEN
    ...

上例中，通过”TB_GW_HOST“、”TB_GW_PORT“和”TB_GW_ACCESS_TOKEN“环境变量，分别将”host.docker.internal“设为host，1883设为port，”YOUR_ACCESS_TOKEN“设为access token。

下列环境变量可用于配置ThingsBoard IoT Gateway：

ENV variable Default value 说明
TB_GW_HOST host.docker.internal ThingsBoard服务器的主机名或IP地址。
TB_GW_PORT 1883 ThingsBoard服务器上的MQTT服务端口。
TB_GW_ACCESS_TOKEN YOUR_ACCESS_TOKEN ThingsBoard中网关的访问令牌。
TB_GW_CA_CERT   CA证书文件路径。
TB_GW_PRIVATE_KEY   私钥文件路径。
TB_GW_CERT   证书文件路径。
TB_GW_CLIENT_ID   ThingsBoard端网关的MQTT客户端ID。
TB_GW_USERNAME   ThingsBoard端网关的MQTT用户名。
TB_GW_PASSWORD   ThingsBoard端网关的MQTT密码。
TB_GW_RATE_LIMITS 15:1,300:60, 向ThingsBoard发送消息的速率限制，格式为 MESSSAGE_COUNT:TIME,。
TB_GW_DP_RATE_LIMITS 15:1,300:60, 向ThingsBoard发送数据点的速率限制，格式为 DATA_POINTS_COUNT:TIME,。
TB_GW_LOGS_PATH /thingsboard_gateway/logs 日志目录路径。

通用配置文件

主配置文件用于连接ThingsBoard平台实例及启用/禁用connector。

以下示例将连接位于thingsboard.cloud的ThingsBoard实例，使用内存存储，最多保存100,000条记录。 示例中启用了4种connector。若只需一种，可从配置中移除其余connector。

主配置文件示例。点击展开。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

{
  "thingsboard": {
    "host": "thingsboard.cloud",
    "port": 1883,
    "remoteShell": false,
    "remoteConfiguration": true,
    "statistics": {
      "enable": true,
      "statsSendPeriodInSeconds": 60
    },
    "deviceFiltering": {
      "enable": false,
      "filterFile": "list.json"
    },
    "maxPayloadSizeBytes": 1024,
    "minPackSendDelayMS": 60,
    "minPackSizeToSend": 500,
    "checkConnectorsConfigurationInSeconds": 10,
    "handleDeviceRenaming": true,
    "security": {
      "type": "accessToken",
      "accessToken": "YOUR_ACCESS_TOKEN"
    },
    "qos": 1,
    "checkingDeviceActivity": {
      "checkDeviceInactivity": false,
      "inactivityTimeoutSeconds": 200,
      "inactivityCheckPeriodSeconds": 500
    }
  },
  "storage": {
    "type": "memory",
    "read_records_count": 100,
    "max_records_count": 10000
  },
  "grpc": {
    "enabled": false,
    "serverPort": 9595,
    "keepaliveTimeMs": 10000,
    "keepaliveTimeoutMs": 5000,
    "keepalivePermitWithoutCalls": true,
    "maxPingsWithoutData": 0,
    "minTimeBetweenPingsMs": 10000,
    "minPingIntervalWithoutDataMs": 5000,
    "keepAliveTimeMs": 10000,
    "keepAliveTimeoutMs": 5000
  },
  "connectors": [
    {
      "type": "mqtt",
      "name": "MQTT Broker Connector",
      "configuration": "mqtt.json"
    },
    {
      "type": "modbus",
      "name": "Modbus Connector",
      "configuration": "modbus.json"
    },
    {
      "type": "modbus",
      "name": "Modbus Serial Connector",
      "configuration": "modbus_serial.json"
    },
    {
      "type": "opcua",
      "name": "OPC-UA Connector",
      "configuration": "opcua.json"
    }
  ]
}

配置文件各区块

  • thingsboard –连接ThingsBoard平台的配置。
    • security –加密与鉴权类型配置。
  • storage –设备上报数据的本地存储配置。
  • connectors – connector数组及其配置。

连接ThingsBoard

参数 默认值 说明
thingsboard   连接服务器的配置。
host thingsboard.cloud ThingsBoard服务器的主机名或IP地址。
port 1883 ThingsBoard服务器上的MQTT服务端口。
qos 1 QoS级别：0（最多一次）和1（至少一次）。
minPackSendDelayMS 200 发送数据包之间的延迟（降低此值将增加CPU占用）。
minPackSizeToSend 500 发送数据包的最小大小。

子区块「statistics」

该子区块用于配置统计数据的采集及上报至ThingsBoard网关设备属性。

参数 默认值 说明
statistics   启用统计采集的配置。
… enable true 布尔值，用于开启/关闭统计采集。
… statsSendPeriodInSeconds 3600 整数，表示定期发送数据的间隔（秒）。
… configuration statistics.json 额外用户统计数据配置文件名（单位：秒）。

可定义额外参数「configuration」，并提供自定义命令采集附加数据。 配置文件示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

[
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "ps -A -o cpu,%mem | awk '{cpu += $1}END{print cpu}'"],
    "attributeOnGateway": "CPU"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "ps -A -o %cpu,%mem | awk '{mem += $2}END{print mem}'"],
    "attributeOnGateway": "Memory"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "ipconfig getifaddr en0"],
    "attributeOnGateway": "IP address"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "sw_vers -productName"],
    "attributeOnGateway": "OS"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "uptime"],
    "attributeOnGateway": "Uptime"
  },
  {
    "timeout": 100,
    "command": ["/bin/sh", "-c", "system_profiler SPUSBDataType"],
    "attributeOnGateway": "USBs"
  }
]

不同操作系统（Linux、macOS、Windows）的示例文件可参见 /config/statistics/ 目录。

子区块「deviceFiltering」

该子区块为可选，用于过滤允许向ThingsBoard发送数据的设备。

设备过滤功能可按指定条件定义过滤规则。

参数 默认值 说明
deviceFiltering   设备过滤配置。
… enable false 布尔值，用于开启/关闭设备过滤。
… filterFile list.json 配置文件名。

配置文件示例如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "deny": {
    "MQTT Broker Connector": [
      "Temperature Device",
      "(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$)"
    ],
    "Modbus Connector": [
      "My Modbus Device"
    ]
  },
  "allow": {
    "MQTT Broker Connector": [
      "My Temperature Sensor"
    ]
  }
}

上述配置包含两个主要属性：「deny」和「allow」。每个属性的键为connector类型，值为设备名称数组。

「deny」用于指定哪些设备被禁止访问指定的connector。列在各connector名称下的设备将被阻止访问该connector。

「deny」属性结构如下：

1
2
3
4
5
6
7
8

"deny": {
  "<Connector Name>": [
    "<Device Name 1>",
    "<Device Name 2>",
    ...
  ],
  ...
}

示例：

1
2
3
4
5
6
7
8
9

"deny": {
  "MQTT Broker Connector": [
    "Temperature Device",
    "(^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+$)"
  ],
  "Modbus Connector": [
    "My Modbus Device"
  ]
}

上例中定义的规则为： *设备「Temperature Device」及任何符合邮箱格式的设备均被禁止访问「MQTT Broker Connector」。 *设备「My Modbus Device」被禁止访问「Modbus Connector」。

「allow」用于指定明确允许访问特定connector的设备。列在各connector下的设备将拥有该connector的完全访问权限。

「allow」属性结构如下：

1
2
3
4
5
6
7
8

"allow": {
  "<Connector Name>": [
    "<Device Name 1>",
    "<Device Name 2>",
    ...
  ],
  ...
}

示例：

1
2
3
4
5

"allow": {
  "MQTT Broker Connector": [
    "My Temperature Sensor"
  ]
}

上例中定义的规则为： *设备「My Temperature Sensor」被允许访问「MQTT Broker Connector」。

设备过滤功能通过设备名称灵活定义允许或禁止访问connector的规则。使用「deny」和「allow」可方便控制网关内设备的访问权限。

子区块「checkingDeviceActivity」

该子区块为可选，用于监控每个已连接设备的活跃度。

定义该区块后，网关将按间隔秒数检查各设备活跃度；若设备在指定秒数内无活动，网关将断开该设备。

参数 默认值 说明
checkingDeviceActivity   设备活跃度检查配置。
… checkDeviceInactivity false 布尔值，用于开启/关闭设备活跃度检查。
… inactivityTimeoutSeconds 120 设备无活动时长，超过后网关将断开。
… inactivityCheckPeriodSeconds 10 设备活跃度检查周期（秒）。

子区块「security」

security子区块共3种配置方式：

访问令牌基础安全
用户名和密码基础安全
TLS+访问令牌高级安全
TLS+私钥高级安全

accessToken 是一种安全配置方式。 请登录 ThingsBoard 平台实例，进入”设备”标签页，点击加号图标， 填写相应信息并勾选”Is gateway（作为网关）”选项， 打开该设备并点击”COPY ACCESS TOKEN（复制访问令牌）”按钮，将默认值替换为您的令牌

参数 默认值 说明
accessToken PUT_YOUR_GW_ACCESS_TOKEN_HERE ThingsBoard 服务器分配给网关的访问令牌。

配置文件中的 security 配置小节将如下所示：

1
2
3
4
5

...
"security": {
  "accessToken": "YOUR_ACCESS_TOKEN"
},
...

一种安全配置方式为使用 clientId、username 和 password。获取方式为：登录 ThingsBoard 平台实例， 进入”设备”标签页，点击加号图标，填写相应信息并勾选”Is gateway（作为网关）”选项， 点击”Next: Credentials（下一步：凭据）”，勾选”Add credentials（添加凭据）”， 选择凭据类型”MQTT Basic”，将默认值替换为您的值。

参数 默认值 说明
clientId clientId 网关在ThingsBoard 服务器上的 MQTT 客户端 ID
username admin 网关在ThingsBoard 服务器上的 MQTT 用户名
password admin 网关在ThingsBoard 服务器上的 MQTT 密码 
1
2
3
4
5
6
7

...
"security": {
  "clientId": "YOUR_CLIENT_ID",
  "username": "YOUR_USERNAME",
  "password": "YOUR_PASSWORD"
},
...

下表描述了在ThingsBoard 平台上配置 IoT Gateway 授权的参数。

参数 默认值 说明
accessToken PUT_YOUR_GW_ACCESS_TOKEN_HERE ThingsBoard 服务器分配给网关的访问令牌。
caCert /etc/thingsboard-gateway/mqttserver.pub.pem CA 证书文件路径。

配置文件中的 security 配置小节将如下所示：

1
2
3
4
5
6

...
"security": {
  "accessToken": "PUT_YOUR_GW_ACCESS_TOKEN_HERE",
  "caCert": "/etc/thingsboard-gateway/mqttserver.pub.pem"
},
...

下表描述了在ThingsBoard 平台上配置 IoT Gateway 授权的参数。

参数 默认值 说明
caCert /etc/thingsboard-gateway/ca.pem CA 证书文件路径。
privateKey /etc/thingsboard-gateway/privateKey.pem 私钥文件路径。
cert /etc/thingsboard-gateway/certificate.pem 证书文件路径。
checkCertPeriod 86400 检查证书有效性的周期（秒）
certificateDaysLeft 3 证书到期前多少天将生成新证书

配置文件中的 security 配置小节将如下所示：

1
2
3
4
5
6
7
8
9

...
"security": {
  "caCert": "/etc/thingsboard-gateway/ca.pem",
  "privateKey": "/etc/thingsboard-gateway/privateKey.pem",
  "cert": "/etc/thingsboard-gateway/certificate.pem",
  "checkCertPeriod": 86400,
  "certificateDaysLeft": 3
},
...

子区块「provisioning」

供应配置共有4种选项（更多供应说明见官方文档）：

自动服务器生成访问令牌
访问令牌预定义访问令牌
基本MQTT基本MQTT凭据
X.509 Certificate

使用以下配置，可将 Gateway 设置为通过服务器 provisioning 策略使用自动生成的 Access Token：

参数 默认值 说明
type AUTO Provisioning 策略类型。
provisionDeviceKey DEVICE_KEY Provisioning 设备密钥，需从已配置的 device profile 中获取。
provisionDeviceSecret DEVICE_SECRET Provisioning 设备密文，需从已配置的 device profile 中获取。

配置文件中的 provisioning 配置小节将如下所示：

1
2
3
4
5
6
7

...
"provisioning": {
  "type": "AUTO",
  "provisionDeviceKey": "PUT_YOUR_DEVICE_KEY_HERE",
  "provisionDeviceSecret": "PUT_YOUR_DEVICE_SECRET_HERE"
},
...

使用以下配置，可将 Gateway 设置为使用 Access Token provisioning 策略：

参数 默认值 说明
type ACCESS_TOKEN Provisioning 策略类型。
provisionDeviceKey DEVICE_KEY Provisioning 设备密钥，需从已配置的 device profile 中获取。
provisionDeviceSecret DEVICE_SECRET Provisioning 设备密文，需从已配置的 device profile 中获取。

配置文件中的 provisioning 配置小节将如下所示：

1
2
3
4
5
6

...
  provisioning:
    type: ACCESS_TOKEN
    provisionDeviceKey: PUT_YOUR_DEVICE_KEY_HERE
    provisionDeviceSecret: PUT_YOUR_DEVICE_SECRET_HERE
...

使用以下配置，可将 Gateway 设置为使用 MQTT Basic provisioning 策略：

参数 默认值 说明
type MQTT_BASIC Provisioning 策略类型。
provisionDeviceKey DEVICE_KEY Provisioning 设备密钥，需从已配置的 device profile 中获取。
provisionDeviceSecret DEVICE_SECRET Provisioning 设备密文，需从已配置的 device profile 中获取。

配置文件中的 provisioning 配置小节将如下所示：

1
2
3
4
5
6
7

...
"provisioning": {
  "type": "MQTT_BASIC",
  "provisionDeviceKey": "PUT_YOUR_DEVICE_KEY_HERE",
  "provisionDeviceSecret": "PUT_YOUR_DEVICE_SECRET_HERE"
},
...

使用以下配置，可将 Gateway 设置为使用 X.509 证书 provisioning 策略：

参数 默认值 说明
type X509_CERTIFICATE Provisioning 策略类型。
provisionDeviceKey DEVICE_KEY Provisioning 设备密钥，需从已配置的 device profile 中获取。
provisionDeviceSecret DEVICE_SECRET Provisioning 设备密文，需从已配置的 device profile 中获取。
caCert ca-root.pem ThingsBoard 中设备的 X509 公钥。

配置文件中的 provisioning 配置小节将如下所示：

1
2
3
4
5
6
7
8

...
"provisioning": {
  "type": "X509_CERTIFICATE",
  "provisionDeviceKey": "PUT_YOUR_DEVICE_KEY_HERE",
  "provisionDeviceSecret": "PUT_YOUR_DEVICE_SECRET_HERE",
  "caCert": "/etc/thingsboard-gateway/ca.pem"
},
...

存储配置

storage子区块用于配置在将数据发送至ThingsBoard平台前的本地保存方式。

该区块共有3种类型：memory、file、SQLite。

  1. Memory存储-将接收的数据保存到内存。
  2. File存储-将接收的数据保存到硬盘。
  3. SQLite存储-将接收的数据保存到 .db文件。
内存存储
(适用于开发环境或磁盘空间有限时的低数据量场景)
SQLite存储
(高性能磁盘持久化——推荐用于大多数生产环境)
文件存储
(简单磁盘持久化——适用于中小规模负载)(旧版)
参数 默认值 说明
type memory 存储类型（将数据保存到内存，不写入硬盘）。
read_records_count 10 从存储中读取并发送到 ThingsBoard 的消息数量。
max_records_count * 100 发送到 ThingsBoard 前存储的最大数据量。

* – 若存储数据量已达该参数值，新收到的数据将会丢失。

配置文件中的 storage 部分如下所示：

1
2
3
4
5
6
7

...
"storage": {
  "type": "memory",
  "read_records_count": 10,
  "max_records_count": 100
},
...
参数 默认值 说明
type sqlite 存储类型（将数据保存到 .db 文件）。
data_file_path ./data/ 存放数据库文件的目录路径（不含文件名）。需要以路径分隔符结尾。
max_read_records_count 1000 从存储中读取并发送到 ThingsBoard 的最大消息数量。
size_limit * 1024 每个 SQLite 文件的最大大小（兆字节）。超过后触发轮换到新 DB 文件。
max_db_amount * 10 磁盘上保留的轮换 DB 文件最大数量。达到后，后续写入将被丢弃直至清理完成。
oversize_check_period 1 检查当前 DB 文件大小是否超过 size_limit 的频率（分钟）。
writing_batch_size 1000 单次写入请求中，写入 DB 前收集的最大消息数量。
messages_ttl_check_in_hours 1 Gateway 检查数据过期的时间间隔（小时）。
messages_ttl_in_days 7 各 DB 中消息的自动删除保留天数。

* –- 若 DB 文件数量达到 max_db_amount 且最后一个数据库超过 size_limit，新数据将丢失，直到之前的数据从数据库读取并传递到平台。 请注意：默认数据库文件名为 data.db。

配置文件中的 storage 部分如下所示：

1
2
3
4
5
6
7
8
9
10
11
12
13

...
"storage": {
  "type": "sqlite",
  "data_file_path": "./data/", 
  "max_read_records_count": 1000,
  "size_limit": 1024,
  "max_db_amount": 10,
  "oversize_check_period": 1,
  "writing_batch_size": 1000,
  "messages_ttl_check_in_hours": 1,
  "messages_ttl_in_days": 7
},
...
参数 默认值 说明
type file 存储类型（将数据保存到硬盘）
data_folder_path ./data/ 存放数据的文件夹路径（相对或绝对路径）。
max_read_records_count 6 从存储中读取并发送到 ThingsBoard 的消息数量。
max_file_count * 5 保存的文件最大数量。
max_records_per_file * 14 单文件存储的最大记录数。

* – 若数据量已达该参数，新收到的数据将会丢失。

配置文件中的 storage 部分如下所示：

1
2
3
4
5
6
7
8
9

...
"storage": {
  "type": "file",
  "data_folder_path": "./data/",
  "max_file_count": 5,
  "max_read_records_count": 6,
  "max_records_per_file": 14
},
...

Connectors配置

connectors区块用于配置通过已实现协议连接设备的connector。 每个connector的配置需包含下表所列参数：

参数 默认值 说明
useGRPC true 可选，用于开启/关闭默认connector的GRPC传输
name MQTT Broker Connector connector名称。
type mqtt connector类型，需与配置文件所在目录名一致。
configuration mqtt.json config目录下配置文件名。*

* –配置文件所在目录。

配置文件中的connectors区块可不同于下述示例，但结构应保持一致：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

...
"connectors": [
  {
    "type": "mqtt",
    "name": "MQTT Broker Connector",
    "configuration": "mqtt.json"
  },
  {
    "type": "modbus",
    "name": "Modbus Connector",
    "configuration": "modbus.json"
  },
  {
    "type": "modbus",
    "name": "Modbus Serial Connector",
    "configuration": "modbus_serial.json"
  },
  {
    "type": "opcua",
    "name": "OPC-UA Connector",
    "configuration": "opcua.json"
  }
]
...

注意：可同时使用多个同类型connector，但需为各自指定不同的名称和配置文件。

如需其他类型的connector，可参考自定义指南自行实现，或发送邮件至：info@thingsboard.io。