目录
在 Ubuntu Server 上安装 ThingsBoard CE
前置条件
本指南介绍如何在Ubuntu 22.04 LTS / 24.04 LTS上安装ThingsBoard。
硬件要求取决于所选数据库及连接系统的设备数量。
在同一台机器上运行ThingsBoard和PostgreSQL至少需要4GB内存。
在同一台机器上运行ThingsBoard和Cassandra至少需要8GB内存。
检查是否已安装所需的字体库:
1
| dpkg -l libharfbuzz0b fontconfig fonts-dejavu-core
|
预期结果:已安装的包会在输出中显示状态为ii。
如果某些库缺失或状态不同,请使用以下命令安装:
1
| sudo apt update && sudo apt install -y libharfbuzz0b fontconfig fonts-dejavu-core
|
步骤1. 安装Java 17 (OpenJDK)
ThingsBoard 服务运行在 Java 17 上。请按以下说明安装 OpenJDK 17:
1
| sudo apt update && sudo apt install openjdk-17-jdk-headless
|
将您的操作系统配置为默认使用 OpenJDK 17。您可以通过运行以下命令来配置默认版本:
1
| sudo update-alternatives --config java
|
要检查系统上已安装的 Java 版本,请使用以下命令:
预期输出为:
1
2
3
| openjdk version "17.x.xx"
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (...)
|
步骤2. ThingsBoard服务安装
下载安装包。
1
| wget https://github.com/thingsboard/thingsboard/releases/download/v4.3.0.1/thingsboard-4.3.0.1.deb
|
将ThingsBoard安装为服务
1
| sudo dpkg -i thingsboard-4.3.0.1.deb
|
步骤3. 配置ThingsBoard数据库
ThingsBoard 可使用 SQL 或混合数据库方案。详见对应架构 页面。
ThingsBoard 团队推荐在开发和合理负载(< 5000 msg/sec)的生产环境中使用 PostgreSQL。 许多云服务商支持托管 PostgreSQL 服务器,对于大多数 ThingsBoard 实例来说这是性价比高的解决方案。
PostgreSQL 安装
要安装 PostgreSQL 数据库,请运行以下命令:
1
2
3
4
5
6
7
8
| # Automated repository configuration:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
# install and launch the postgresql service:
sudo apt update
sudo apt -y install postgresql-16
sudo service postgresql start
|
安装 PostgreSQL 后,建议为 PostgreSQL 主用户 设置密码。
以下命令将切换当前用户为 PostgreSQL 用户并在 PostgreSQL 中直接设置密码。
1
| sudo -u postgres psql -c "\password"
|
然后输入并确认密码。
然后,以 “postgres” 用户身份连接 “postgres” 数据库:
1
| psql -U postgres -d postgres -h 127.0.0.1 -W
|
创建名为 “thingsboard” 的 ThingsBoard 数据库:
1
| CREATE DATABASE thingsboard;
|
按两次 “Ctrl+D” 退出 PostgreSQL。
ThingsBoard 配置
编辑 ThingsBoard 配置文件
1
| sudo nano /etc/thingsboard/conf/thingsboard.conf
|
将以下内容添加到配置文件中。请勿忘记替换 “PUT_YOUR_POSTGRESQL_PASSWORD_HERE” 为您的真实 postgres 用户密码:
1
2
3
4
5
6
7
| # DB Configuration
export DATABASE_TS_TYPE=sql
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/thingsboard
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE
# Specify partitioning size for timestamp key-value storage. Allowed values: DAYS, MONTHS, YEARS, INDEFINITE.
export SQL_POSTGRES_TS_KV_PARTITIONING=MONTHS
|
|
ThingsBoard 团队建议:若计划在生产环境中部署 100 万以上设备或具有高数据采集率(> 5000 条/秒),请使用混合数据库方案。 此方案下,ThingsBoard 将时序数据存储于 Cassandra,同时继续使用 PostgreSQL 存储主要实体(设备/资产/仪表板/客户)。
PostgreSQL 安装
要安装 PostgreSQL 数据库,请运行以下命令:
1
2
3
4
5
6
7
8
| # Automated repository configuration:
sudo apt install -y postgresql-common
sudo /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh
# install and launch the postgresql service:
sudo apt update
sudo apt -y install postgresql-16
sudo service postgresql start
|
安装 PostgreSQL 后,建议为 PostgreSQL 主用户 设置密码。
以下命令将切换当前用户为 PostgreSQL 用户并在 PostgreSQL 中直接设置密码。
1
| sudo -u postgres psql -c "\password"
|
然后输入并确认密码。
然后,以 “postgres” 用户身份连接 “postgres” 数据库:
1
| psql -U postgres -d postgres -h 127.0.0.1 -W
|
创建名为 “thingsboard” 的 ThingsBoard 数据库:
1
| CREATE DATABASE thingsboard;
|
按两次 “Ctrl+D” 退出 PostgreSQL。
Cassandra 安装
以下命令将安装 Apache Cassandra 及其命令行工具:
1
2
3
4
5
6
| # 添加 Cassandra 软件源
echo "deb [signed-by=/etc/apt/keyrings/apache-cassandra.asc] https://debian.cassandra.apache.org 50x main" | sudo tee /etc/apt/sources.list.d/cassandra.sources.list
sudo curl -o /etc/apt/keyrings/apache-cassandra.asc https://downloads.apache.org/cassandra/KEYS
sudo apt-get update
# 安装 Cassandra
sudo apt-get install -y cassandra cassandra-tools
|
要验证 Cassandra 是否正常运行,请使用以下命令检查节点状态和系统服务状态:
1
2
| nodetool status
sudo systemctl status cassandra.service
|
输出中的 status 列应显示 UN(表示 “Up/Normal”);您可能需要等待片刻让 Cassandra 完成初始化。示例输出:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| $ nodetool status
Datacenter: datacenter1
=======================
Status=Up/Down
|/ State=Normal/Leaving/Joining/Moving
-- Address Load Tokens Owns (effective) Host ID Rack
UN 127.0.0.1 114.67 KiB 16 100.0% b8e1bd83-5280-4e48-8b17-a4548eec583b rack1
$ sudo systemctl status cassandra.service
● cassandra.service - LSB: distributed storage system for structured data
Loaded: loaded (/etc/init.d/cassandra; generated)
Active: active (running) since Thu 2025-04-24 14:04:35 UTC; 43s ago
Docs: man:systemd-sysv-generator(8)
Process: 9415 ExecStart=/etc/init.d/cassandra start (code=exited, status=0/SUCCESS)
Tasks: 61 (limit: 9439)
Memory: 4.3G (peak: 4.3G)
CPU: 14.470s
CGroup: /system.slice/cassandra.service
└─9553 /usr/bin/java -ea -da:net.openhft... -XX:+UseThreadPriorities -XX:+HeapDumpOnOutOfMemoryError -Xss256k -XX:+AlwaysPreTouch -XX:+UseTLAB -XX:+ResizeTLAB -XX:+UseNUMA -XX:>
...
|
您可以使用 Astra DB Cloud 替代自建 Cassandra。
参见将 ThingsBoard 连接至 Astra DB 的说明。
ThingsBoard 配置
编辑 ThingsBoard 配置文件
1
| sudo nano /etc/thingsboard/conf/thingsboard.conf
|
将以下行添加到配置文件中。请勿忘记将 “PUT_YOUR_POSTGRESQL_PASSWORD_HERE” 替换为您的实际 postgres 用户密码:
1
2
3
4
5
| # DB Configuration
export DATABASE_TS_TYPE=cassandra
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/thingsboard
export SPRING_DATASOURCE_USERNAME=postgres
export SPRING_DATASOURCE_PASSWORD=PUT_YOUR_POSTGRESQL_PASSWORD_HERE
|
可选的,可添加以下参数以将 ThingsBoard 实例重新配置为连接外部 Cassandra 节点:
1
2
3
4
5
6
| export CASSANDRA_CLUSTER_NAME=Thingsboard Cluster
export CASSANDRA_KEYSPACE_NAME=thingsboard
export CASSANDRA_URL=127.0.0.1:9042
export CASSANDRA_USE_CREDENTIALS=false
export CASSANDRA_USERNAME=
export CASSANDRA_PASSWORD=
|
|
步骤4. 选择ThingsBoard队列服务
ThingsBoard 平台目前支持两种消息 broker 用于存储消息及 ThingsBoard 服务间通信:In-memory 和基于 Kafka 的 broker。
-
In Memory queue 实现为内置且默认。
适用于开发(PoC)环境,不适合生产部署或任何集群部署。
-
Kafka 推荐用于生产部署。该 queue 现已在多数 ThingsBoard 生产环境中使用。
适用于本地部署和私有云部署。若希望独立于云提供商,同样适用。
部分云提供商也提供 Kafka 托管服务,如 AWS MSK。
-
Confluent Cloud 是基于 Kafka 的全托管流平台。适用于云无关部署。
详见对应架构 页面 和规则引擎 页面。
In Memory 队列已内置且默认启用,无需额外配置。
|
Docker 安装
为 Ubuntu 安装 Docker
Kafka 安装
Apache Kafka 是一款开源流处理软件平台。
安装 Kafka
使用以下说明在 Docker 容器中安装 Kafka。
1
| nano docker-compose-kafka.yml
|
将以下内容添加到 docker-compose-kafka.yml 文件:
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
| services:
kafka:
restart: always
image: bitnamilegacy/kafka:4.0
ports:
- 9092:9092 #to localhost:9092 from host machine
- 9093 #for Kraft
- 9094 #to kafka:9094 from within Docker network
environment:
ALLOW_PLAINTEXT_LISTENER: "yes"
KAFKA_CFG_LISTENERS: "OUTSIDE://:9092,CONTROLLER://:9093,INSIDE://:9094"
KAFKA_CFG_ADVERTISED_LISTENERS: "OUTSIDE://localhost:9092,INSIDE://kafka:9094"
KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "INSIDE:PLAINTEXT,OUTSIDE:PLAINTEXT,CONTROLLER:PLAINTEXT"
KAFKA_CFG_INTER_BROKER_LISTENER_NAME: "INSIDE"
KAFKA_CFG_AUTO_CREATE_TOPICS_ENABLE: "false"
KAFKA_OFFSETS_TOPIC_REPLICATION_FACTOR: "1"
KAFKA_TRANSACTION_STATE_LOG_MIN_ISR: "1"
KAFKA_TRANSACTION_STATE_LOG_REPLICATION_FACTOR: "1"
KAFKA_CFG_PROCESS_ROLES: "controller,broker" #KRaft
KAFKA_CFG_NODE_ID: "0" #KRaft
KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER" #KRaft
KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "0@kafka:9093" #KRaft
volumes:
- kafka-data:/bitnami
volumes:
kafka-data:
driver: local
|
启动容器:
1
| docker compose -f docker-compose-kafka.yml up -d
|
ThingsBoard 配置
编辑 ThingsBoard 配置文件
1
| sudo nano /etc/thingsboard/conf/thingsboard.conf
|
将以下行添加到配置文件。请勿忘记将「localhost:9092」替换为实际的 Kafka bootstrap 服务器地址:
1
2
| export TB_QUEUE_TYPE=kafka
export TB_KAFKA_SERVERS=localhost:9092
|
|
Confluent Cloud 配置
要访问 Confluent Cloud,您需要先创建账户,然后创建 Kafka 集群并获取您的 API Key。
ThingsBoard 配置
编辑 ThingsBoard 配置文件
1
| sudo nano /etc/thingsboard/conf/thingsboard.conf
|
将以下内容添加到配置文件中。请勿忘记将 “CLUSTER_API_KEY”、”CLUSTER_API_SECRET” 和 “localhost:9092” 替换为实际的 Confluent Cloud 引导服务器:
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
| export TB_QUEUE_TYPE=kafka
export TB_QUEUE_KAFKA_USE_CONFLUENT_CLOUD=true
export TB_KAFKA_SERVERS=localhost:9092
export TB_QUEUE_KAFKA_REPLICATION_FACTOR=3
export TB_QUEUE_KAFKA_CONFLUENT_SASL_JAAS_CONFIG='org.apache.kafka.common.security.plain.PlainLoginModule required username="CLUSTER_API_KEY" password="CLUSTER_API_SECRET";'
# These params affect the number of requests per second from each partitions per each queue.
# Number of requests to particular Message Queue is calculated based on the formula:
# ((Number of Rule Engine and Core Queues) * (Number of partitions per Queue) + (Number of transport queues)
# + (Number of microservices) + (Number of JS executors)) * 1000 / POLL_INTERVAL_MS
# For example, number of requests based on default parameters is:
# Rule Engine queues:
# Main 10 partitions + HighPriority 10 partitions + SequentialByOriginator 10 partitions = 30
# Core queue 10 partitions
# Transport request Queue + response Queue = 2
# Rule Engine Transport notifications Queue + Core Transport notifications Queue = 2
# Total = 44
# Number of requests per second = 44 * 1000 / 25 = 1760 requests
# Based on the use case, you can compromise latency and decrease number of partitions/requests to the queue, if the message load is low.
# By UI set the parameters - interval (1000) and partitions (1) for Rule Engine queues.
# Sample parameters to fit into 10 requests per second on a "monolith" deployment:
export TB_QUEUE_CORE_POLL_INTERVAL_MS=1000
export TB_QUEUE_CORE_PARTITIONS=2
export TB_QUEUE_RULE_ENGINE_POLL_INTERVAL_MS=1000
export TB_QUEUE_TRANSPORT_REQUEST_POLL_INTERVAL_MS=1000
export TB_QUEUE_TRANSPORT_RESPONSE_POLL_INTERVAL_MS=1000
export TB_QUEUE_TRANSPORT_NOTIFICATIONS_POLL_INTERVAL_MS=1000
export TB_QUEUE_VC_INTERVAL_MS=1000
export TB_QUEUE_VC_PARTITIONS=1
|
您可以通过 UI 更新默认规则引擎队列配置。有关 ThingsBoard 规则引擎队列的更多信息,请参阅文档。
|
步骤5. [可选] 低配机器内存更新(4GB内存)
编辑 ThingsBoard 配置文件
1
| sudo nano /etc/thingsboard/conf/thingsboard.conf
|
在配置文件中添加以下行:
1
2
| # 更新 ThingsBoard 内存使用并限制为 2G,路径:/etc/thingsboard/conf/thingsboard.conf
export JAVA_OPTS="$JAVA_OPTS -Xms2G -Xmx2G"
|
建议根据服务器资源调整这些参数。该值应至少设置为 2G(GB),若有更多可用 RAM 可相应增加。通常,若不运行其他内存密集型进程(如 Cassandra),可设置为总 RAM 的 1/2,否则设为 1/3。
步骤6. 运行安装脚本
ThingsBoard 服务安装完成且 DB 配置更新后,可执行以下脚本:
1
2
| # --loadDemo 选项将加载演示数据:users、devices、assets、rules、部件。
sudo /usr/share/thingsboard/bin/install/install.sh --loadDemo
|
步骤7. 启动ThingsBoard服务
执行以下命令启动 ThingsBoard:
1
| sudo service thingsboard start
|
启动后,可通过以下链接访问 Web UI:
若在运行安装脚本时指定了 –loadDemo,可使用以下默认凭证:
- System Administrator:sysadmin@thingsboard.org / sysadmin
- Tenant Administrator:tenant@thingsboard.org / tenant
- Customer User:customer@thingsboard.org / customer
可随时在账户资料页面修改各账户密码。
安装后步骤
配置HAProxy以启用HTTPS
您可能希望使用 HAProxy 配置 HTTPS 访问。
若在云端托管 ThingsBoard 且已为实例分配有效 DNS 名称,则可实现。
请参阅此指南安装 HAProxy 并使用 Let’s Encrypt 生成有效 SSL 证书。
升级到新版本ThingsBoard
保持平台安全与更新
当有新 ThingsBoard 版本发布时,我们提供简化的更新流程,确保系统获得最新功能和安全补丁,且不危及您的数据。
为保持数据库完整性和系统稳定性,请按顺序进行升级(例如 v4.0.2 → v4.1.0 → v4.2.0)。
请参阅官方 升级说明,获取针对您当前部署环境的详细步骤。
故障排查
ThingsBoard 日志存储在以下目录中:
可使用以下命令检查后端是否有错误:
1
| cat /var/log/thingsboard/thingsboard.log | grep ERROR
|
下一步
-
快速入门指南 - 快速了解ThingsBoard主要功能,约15-30分钟完成。
-
连接设备 - 根据连接技术或方案学习如何连接设备。
-
数据可视化 - 配置ThingsBoard复杂仪表盘的说明。
-
数据处理与操作 - 学习使用ThingsBoard规则引擎。
-
IoT数据分析 - 学习使用规则引擎执行基本分析任务。
-
高级功能 - 了解ThingsBoard高级功能。
-
贡献与开发 - 了解ThingsBoard贡献与开发。