目录
在 CentOS/RHEL 上安装 ThingsBoard CE
前置条件
本指南介绍如何在RHEL 8/9、CentOS 8/9或其衍生版本（Alma、Rocky、Oracle等）上安装ThingsBoard。
硬件要求取决于所选数据库及连接系统的设备数量。
在同一台机器上运行ThingsBoard和PostgreSQL至少需要4GB内存。
在同一台机器上运行ThingsBoard和Cassandra至少需要8GB内存。
继续安装之前，请执行以下命令安装必要工具：
适用于CentOS 8：
1
2
3
4
| # Install wget
sudo dnf install -y nano wget
# Add latest EPEL release for CentOS 8
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
|
适用于CentOS 9：
1
2
3
4
| # Install wget
sudo dnf install -y nano wget
# Add latest EPEL release for CentOS 9
sudo dnf install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
|
为确保安装过程正常，请执行以下命令安装必要的系统字体：
1
| sudo dnf install -y harfbuzz fontconfig dejavu-sans-fonts
|
步骤1. 安装Java 17 (OpenJDK)
ThingsBoard 服务运行在 Java 17 上。请按以下说明安装 OpenJDK 17：
1
| sudo dnf install java-17-openjdk-headless
|
请勿忘记将您的操作系统配置为默认使用 OpenJDK 17。您可以使用以下命令配置默认版本：
1
| sudo update-alternatives --config java
|
您可以使用以下命令检查安装：
预期命令输出为：
1
2
3
| openjdk version "17.x.xx"
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (build ...)
|
步骤2. ThingsBoard服务安装
下载安装包。
1
| wget https://github.com/thingsboard/thingsboard/releases/download/v4.3.0.1/thingsboard-4.3.0.1.rpm
|
将ThingsBoard安装为服务
1
| sudo rpm -Uvh thingsboard-4.3.0.1.rpm
|
步骤3. 配置ThingsBoard数据库
ThingsBoard 可使用 SQL 或混合数据库方案。详见对应架构 页面。
ThingsBoard 团队推荐在开发和合理负载（< 5000 msg/sec）的生产环境中使用 PostgreSQL。 许多云服务商支持托管 PostgreSQL 服务器，对于大多数 ThingsBoard 实例来说这是性价比高的解决方案。
PostgreSQL 安装
以下说明将帮助您安装 PostgreSQL。
1
2
| # Update your system
sudo dnf update
|
安装软件源。
对于 CentOS/RHEL 8：
1
2
| # Install the repository RPM:
sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
|
对于 CentOS/RHEL 9：
1
2
| # Install the repository RPM:
sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
|
安装软件包。
1
2
3
4
5
6
7
8
| # Install packages
sudo dnf -qy module disable postgresql
sudo dnf -y install postgresql16 postgresql16-server postgresql16-contrib
# Initialize your PostgreSQL DB
sudo /usr/pgsql-16/bin/postgresql-16-setup initdb
sudo systemctl start postgresql-16
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable --now postgresql-16
|
安装 PostgreSQL 后，建议为 PostgreSQL 主用户 设置密码。
以下命令将切换当前用户为 PostgreSQL 用户并在 PostgreSQL 中直接设置密码。
1
| sudo -u postgres psql -c "\password"
|
然后输入并确认密码。
配置密码后，连接数据库以创建 thingsboard 数据库：
1
| psql -U postgres -d postgres -h 127.0.0.1 -W
|
执行创建数据库语句：
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
| # Update your system
sudo dnf update
|
安装软件源。
对于 CentOS/RHEL 8：
1
2
| # Install the repository RPM:
sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
|
对于 CentOS/RHEL 9：
1
2
| # Install the repository RPM:
sudo dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
|
安装软件包。
1
2
3
4
5
6
7
8
| # Install packages
sudo dnf -qy module disable postgresql
sudo dnf -y install postgresql16 postgresql16-server postgresql16-contrib
# Initialize your PostgreSQL DB
sudo /usr/pgsql-16/bin/postgresql-16-setup initdb
sudo systemctl start postgresql-16
# Optional: Configure PostgreSQL to start on boot
sudo systemctl enable --now postgresql-16
|
安装 PostgreSQL 后，建议为 PostgreSQL 主用户 设置密码。
以下命令将切换当前用户为 PostgreSQL 用户并在 PostgreSQL 中直接设置密码。
1
| sudo -u postgres psql -c "\password"
|
然后输入并确认密码。
配置密码后，连接数据库以创建 thingsboard 数据库：
1
| psql -U postgres -d postgres -h 127.0.0.1 -W
|
执行创建数据库语句：
1
| CREATE DATABASE thingsboard;
|
然后按两次 “Ctrl+D” 退出 PostgreSQL。
Cassandra 安装
以下命令将安装 Apache Cassandra 及其命令行工具：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
| # 导入 GPG 密钥
sudo rpm --import https://downloads.apache.org/cassandra/KEYS
# 添加 Cassandra 软件源
sudo tee /etc/yum.repos.d/cassandra.repo > /dev/null <<EOF
[cassandra]
name=Apache Cassandra
baseurl=https://redhat.cassandra.apache.org/50x/
gpgcheck=1
repo_gpgcheck=0
gpgkey=https://downloads.apache.org/cassandra/KEYS
EOF
# 安装软件包
sudo dnf -y update
sudo dnf -y install cassandra cassandra-tools chkconfig
# 启动服务
sudo systemctl daemon-reexec
sudo systemctl start cassandra.service
# 配置 Cassandra 开机自启
sudo chkconfig cassandra on
|
要验证 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
21
| $ 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 136.29 KiB 16 100.0% 60ae50fd-8914-44a1-a397-b716b7d4b37c rack1
$ sudo systemctl status cassandra.service
● cassandra.service - LSB: distributed storage system for structured data
Loaded: loaded (/etc/rc.d/init.d/cassandra; generated)
Active: active (running) since Thu 2025-04-24 12:22:11 UTC; 11min ago
Docs: man:systemd-sysv-generator(8)
Process: 34716 ExecStart=/etc/rc.d/init.d/cassandra start (code=exited, status=0/SUCCESS)
Main PID: 34819 (java)
Tasks: 62 (limit: 50538)
Memory: 4.3G
CPU: 17.792s
CGroup: /system.slice/cassandra.service
└─34819 /usr/lib/jvm/java-17-openjdk-17.0.14.0.7-2.el9.x86_64/bin/java -ea -da:net.openhft... -XX:+UseThreadPriorities -XX:+HeapDumpOnOutOfMemoryError -Xss256k -XX:+AlwaysPreTo>
...
|
您可以使用 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 安装
为 CentOS/RHEL 安装 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 UI默认通过端口8080访问。
请确保防火墙已开放8080端口。
请执行以下命令开放8080端口：
1
2
| sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
sudo firewall-cmd --reload
|
执行以下命令启动 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贡献与开发。
