产品定价 立即试用
专业版
安装 > 本地部署 > Ubuntu Server
入门 文档 指南
架构 API 常见问题
目录

在 Ubuntu 上安装 ThingsBoard PE

前置条件

本指南介绍如何在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
java -version

预期输出为:

1
2
3
openjdk version "17.x.xx" 
OpenJDK Runtime Environment (...)
OpenJDK 64-Bit Server VM (...)

步骤2. ThingsBoard服务安装

下载安装包。

1
wget https://dist.thingsboard.io/thingsboard-4.3.0.1pe.deb

将ThingsBoard安装为服务

1
sudo dpkg -i thingsboard-4.3.0.1pe.deb

步骤3. 获取并配置许可证密钥

我们假设您已经选择了订阅计划或决定购买永久许可证。 如果尚未选择,请前往定价页面选择最适合您的许可证方案。 详情请参考如何获取按需订阅或如何获取永久许可证。

获取许可证密钥后,需要将其写入ThingsBoard配置文件。 使用以下命令打开文件进行编辑:

1
sudo nano /etc/thingsboard/conf/thingsboard.conf

找到以下配置块:

1
2
3
# License secret obtained from ThingsBoard License Portal (https://license.thingsboard.io)
# UNCOMMENT NEXT LINE AND PUT YOUR LICENSE SECRET:
# export TB_LICENSE_SECRET=

填入您的许可证密钥。请勿忘记取消export语句的注释。参考以下示例:

1
2
3
# License secret obtained from ThingsBoard License Portal (https://license.thingsboard.io)
# UNCOMMENT NEXT LINE AND PUT YOUR LICENSE SECRET:
export TB_LICENSE_SECRET=YOUR_LICENSE_SECRET_HERE

步骤4. 配置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=

步骤5. 选择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

文档警告图标

不要忘记将 Linux 用户加入 docker 用户组。参见 以非 root 用户管理 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 规则引擎队列的更多信息,请参阅文档。

步骤6. [可选] 低配机器内存更新(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。

步骤7. 运行安装脚本

ThingsBoard 服务安装完成且 DB 配置更新后,可执行以下脚本:

1
2
# --loadDemo 选项将加载演示数据:users、devices、assets、rules、部件。
sudo /usr/share/thingsboard/bin/install/install.sh --loadDemo

步骤8. 启动ThingsBoard服务

执行以下命令启动 ThingsBoard:

1
sudo service thingsboard start

启动后,可通过以下链接访问 Web UI:

1
http://localhost:8080/

若在运行安装脚本时指定了 –loadDemo,可使用以下默认凭证:

  • System Administrator:sysadmin@thingsboard.org / sysadmin
  • Tenant Administrator:tenant@thingsboard.org / tenant
  • Customer User:customer@thingsboard.org / customer

可随时在账户资料页面修改各账户密码。

文档信息图标

Web UI启动最多可能需要90秒。

步骤9. 安装ThingsBoard WebReport组件

前提条件

安装 Docker Ubuntu 版本。

文档警告图标

不要忘记将 Linux 用户加入 docker 用户组。参见 以非 root 用户管理 Docker。

创建 docker compose 文件

1
2
3
4
5
6
7
8
9
10
11
12
cat <<EOT >> tb-web-report.yml
version: '3.0'
services:
  tb-web-report:
    container_name: tb-web-report
    restart: always
    image: "thingsboard/tb-pe-web-report:4.3.0.1PE"
    ports:
      - "8383:8383"
    env_file:
      - ./tb-web-report.env
EOT

为 tb-web-report 容器创建 .env 文件

1
2
3
4
5
6
7
8
9
10
11
12
cat <<EOT >> tb-web-report.env
HTTP_BIND_ADDRESS=0.0.0.0
HTTP_BIND_PORT=8383
LOGGER_LEVEL=info
LOG_FOLDER=logs
LOGGER_FILENAME=tb-web-report-%DATE%.log
DOCKER_MODE=true

DEFAULT_PAGE_NAVIGATION_TIMEOUT=120000
DASHBOARD_LOAD_WAIT_TIME=3000
USE_NEW_PAGE_FOR_REPORT=true
EOT

在 Docker 中启动 WebReport 服务

1
docker compose -f tb-web-report.yml up -d

容器故障排查

从容器读取日志

1
docker logs -f tb-web-report

下载 Reports Server 组件的安装包:

1
wget https://dist.thingsboard.io/tb-web-report-4.3.0.1pe.deb

安装第三方库:

1
2
3
4
5
sudo apt install -yq  libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 \
     libexpat1 libfontconfig1 libgcc1  libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 \
     libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
     libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 \
     ca-certificates fonts-liberation libnss3 lsb-release xdg-utils unzip wget libgbm-dev

安装 Roboto 字体:

1
sudo apt install fonts-roboto

安装 Noto 字体(日语、中文等):

1
2
3
4
5
6
7
8
9
10
mkdir ~/noto
cd ~/noto
wget https://src.fedoraproject.org/repo/extras/chromium/NotoSansCJKjp-hinted.zip/sha512/e7bcbc53a10b8ec3679dcade5a8a94cea7e1f60875ab38f2193b4fa8e33968e1f0abc8184a3df1e5210f6f5c731f96c727c6aa8f519423a29707d2dee5ada193/NotoSansCJKjp-hinted.zip
unzip NotoSansCJKjp-hinted.zip
sudo mkdir -p /usr/share/fonts/noto
sudo cp *.otf /usr/share/fonts/noto
sudo chmod 655 -R /usr/share/fonts/noto/
sudo fc-cache -fv
cd ..
rm -rf ~/noto

安装并启动 Web Report 服务:

1
2
sudo dpkg -i tb-web-report-4.3.0.1pe.deb
sudo service tb-web-report start

安装后步骤

配置HAProxy以启用HTTPS

您可能希望使用 HAProxy 配置 HTTPS 访问。 若在云端托管 ThingsBoard 且已为实例分配有效 DNS 名称,则可实现。 请参阅此指南安装 HAProxy 并使用 Let’s Encrypt 生成有效 SSL 证书。

升级到新版本ThingsBoard

保持平台安全与更新

当有新 ThingsBoard 版本发布时,我们提供简化的更新流程,确保系统获得最新功能和安全补丁,且不危及您的数据。

文档信息图标

为保持数据库完整性和系统稳定性,请按顺序进行升级(例如 v4.0.2 → v4.1.0 → v4.2.0)。

请参阅官方 升级说明,获取针对您当前部署环境的详细步骤。

故障排查

ThingsBoard 日志存储在以下目录中:

1
/var/log/thingsboard

可使用以下命令检查后端是否有错误:

1
cat /var/log/thingsboard/thingsboard.log | grep ERROR

下一步