ThingsBoard Edge Ubuntu 安装全指南：从 OpenJDK 25 到云边连接（.deb 包实战）-平芜编程栈

物联网
后端
数据可视化
消息队列

【免费下载链接】thingsboard

All-in-one IoT Platform - Device management, data collection, processing and visualization.

项目地址：https://gitcode.com/GitHub_Trending/th/thingsboard

本指南以 ThingsBoard 官方 Ubuntu 安装文档为主体，完整讲解在 Ubuntu Server 上通过 .deb 包快速安装 ThingsBoard Edge 并连接到云服务器的全部七个步骤：Java 25 环境准备、PostgreSQL 16 数据库配置、Edge 服务安装、云边 RPC 连接参数与可选端口调整，以及最终的安装脚本执行与 UI 登录验证。读完本文，你将掌握一套可复制的云边部署流程，并理解每个配置项背后的源码实现与端口占用原理。

文档来源：ubuntu/instructions.md。文中出现的${CLOUD_ROUTING_KEY}、${BASE_URL}等占位符并非真实值，而是 ThingsBoard 服务器端在渲染安装指南时自动替换的动态变量（详见下文"占位符如何被替换"）。

安装前的系统要求

在开始之前，请确认你的 Ubuntu 版本满足最低要求：

OpenJDK 25 要求 Ubuntu 22.04 LTS 或更新版本。文档明确注明：20.04 及更早版本不受支持（Note: OpenJDK 25 requires Ubuntu 22.04 LTS or newer. Earlier versions (20.04 and below) are not supported.）。
需要sudo权限来安装系统包、管理 PostgreSQL 服务以及启动 ThingsBoard Edge 系统服务。
若 ThingsBoard Edge 与 ThingsBoard Server 安装在同一台机器上，需预留下文"更新绑定端口"一节所述的端口空间。

Step 1. 安装 Java 25（OpenJDK）

ThingsBoard Edge 服务运行在 Java 25 之上。首先更新软件源并安装 OpenJDK 25 的 JDK 包：

sudo apt update && sudo apt install openjdk-25-jdk

安装完成后，将操作系统默认 Java 切换到 OpenJDK 25：

sudo update-alternatives --config java

该命令会列出系统已安装的所有 Java 版本，选择对应 OpenJDK 25 的编号即可。验证安装结果：

java -version

预期输出类似：

openjdk version "25.x.xx" OpenJDK Runtime Environment (...) OpenJDK 64-Bit Server VM (build ...)

若系统中存在多个 JDK，update-alternatives是确保 ThingsBoard 启动时使用正确运行时版本的可靠手段。

Step 2. 配置 ThingsBoard Edge 数据库

ThingsBoard Edge 支持SQL与hybrid（SQL + Cassandra）两种数据库配置。本文按文档使用SQL数据库（PostgreSQL）。hybrid 模式的具体步骤请参考官方安装文档站点的 Edge 安装章节。

安装 PostgreSQL 16

# 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-common与官方apt.postgresql.org.sh脚本自动配置 PostgreSQL 软件源，随后安装 PostgreSQL 16 并启动服务。

设置 PostgreSQL 主用户密码

安装完成后，建议为 PostgreSQL 主用户postgres设置密码。以下命令会切换到postgres系统用户，并在 PostgreSQL 内部直接执行密码设置：

sudo -u postgres psql -c "\password"

按提示输入并确认密码即可。请务必牢记该密码，后续步骤与配置文件都会用到。

创建 tb_edge 数据库

最后创建名为tb_edge的数据库：

echo "CREATE DATABASE tb_edge;" | psql -U postgres -d postgres -h 127.0.0.1 -W

执行时会提示输入 PostgreSQL 密码（即上一步设置的密码）。该命令通过本机127.0.0.1回环地址以 TCP 方式连接 PostgreSQL 并创建数据库。

提示：psql的-W参数强制提示输入密码；-d postgres指定初始连接库（PostgreSQL 默认自带），-h 127.0.0.1指定本机 TCP 连接。若你希望直接交互式执行，也可以使用psql -U postgres -h 127.0.0.1 -W进入 psql 提示符后执行CREATE DATABASE tb_edge;。

Step 3. 安装 ThingsBoard Edge 服务（.deb 包）

下载安装包：

wget https://dist.thingsboard.io/tb-edge-${TB_EDGE_TAG}pe.deb

然后安装该 .deb 包：

sudo dpkg -i tb-edge-${TB_EDGE_TAG}pe.deb

其中${TB_EDGE_TAG}是 ThingsBoard Edge 的版本标签占位符，由服务器端在渲染指南时自动替换为实际版本（详见下文源码解析）。安装完成后，Edge 服务的配置文件位于/etc/tb-edge/conf/tb-edge.conf，安装脚本位于/usr/share/tb-edge/bin/install/install.sh。

Step 4. 配置 ThingsBoard Edge

配置云边连接参数

使用以下命令向配置文件追加云边连接的核心参数：

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf export CLOUD_ROUTING_KEY=${CLOUD_ROUTING_KEY} export CLOUD_ROUTING_SECRET=${CLOUD_ROUTING_SECRET} export CLOUD_RPC_HOST=${BASE_URL} export CLOUD_RPC_PORT=${CLOUD_RPC_PORT} export CLOUD_RPC_SSL_ENABLED=${CLOUD_RPC_SSL_ENABLED} EOL'

各参数含义：

参数	含义
`CLOUD_ROUTING_KEY`	该 Edge 实例在云服务器上的路由标识（routing key），由服务器在创建 Edge 时生成
`CLOUD_ROUTING_SECRET`	与 routing key 配对的通信密钥，用于云边连接鉴权
`CLOUD_RPC_HOST`	云服务器（ThingsBoard Server / Cloud）的主机名或 IP，Edge 据此发起 RPC 长连接
`CLOUD_RPC_PORT`	云边 RPC 服务器端口，默认值为7070
`CLOUD_RPC_SSL_ENABLED`	是否启用云边 RPC 的 SSL 加密（`true`/`false`）

占位符如何被替换（源码佐证）

这份指南文档并不是静态文件：服务器端在向用户展示安装指南时，会通过 DefaultEdgeInstallInstructionsService.java 动态替换占位符。从源码可以看到：

getLinuxInstallInstructions(...)读取install/ubuntu/instructions.md（或 centos 版本），并依次调用replacePlaceholders(...)与.replace("${BASE_URL}", request.getServerName())；
replacePlaceholders(...)将${CLOUD_ROUTING_KEY}替换为edge.getRoutingKey()、${CLOUD_ROUTING_SECRET}替换为edge.getSecret()，端口与 SSL 开关则取自服务器配置edges.rpc.port与edges.rpc.ssl.enabled。

对应到服务器端配置，位于 thingsboard.yml：

edges: enabled: "${EDGES_ENABLED:true}" rpc: port: "${EDGES_RPC_PORT:7070}" ssl: enabled: "${EDGES_RPC_SSL_ENABLED:false}"

即云边 RPC 默认监听7070端口，默认不启用 SSL。这意味着 Edge 必须能通过该端口访问到云服务器的 7070 端口（局域网内部署时注意防火墙与安全组放行）。

[可选] 配置 PostgreSQL 连接

如果你修改过 PostgreSQL 默认数据源设置，请追加以下配置：

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/tb_edge export SPRING_DATASOURCE_USERNAME=postgres export SPRING_DATASOURCE_PASSWORD=<PUT_YOUR_POSTGRESQL_PASSWORD_HERE> EOL'

SPRING_DATASOURCE_URL：JDBC 连接串，指向本机 5432 端口的tb_edge数据库；
SPRING_DATASOURCE_USERNAME：数据库用户名，默认postgres；
SPRING_DATASOURCE_PASSWORD：将<PUT_YOUR_POSTGRESQL_PASSWORD_HERE>替换为你第 2 步中设置的实际 PostgreSQL 用户密码。

说明：Spring Boot 会自动读取以SPRING_DATASOURCE_开头的环境变量映射为数据源配置，无需额外手动修改其他文件。

[可选] 更新绑定端口（与 ThingsBoard Server 同机部署时）

如果 ThingsBoard Edge 与 ThingsBoard Server 运行在同一台机器上，必须调整端口以避免两个服务冲突：

sudo sh -c 'cat <<EOL >> /etc/tb-edge/conf/tb-edge.conf export HTTP_BIND_PORT=18080 export MQTT_BIND_PORT=11883 export COAP_BIND_PORT=15683 export LWM2M_ENABLED=false export SNMP_ENABLED=false export INTEGRATIONS_RPC_PORT=19090 EOL'

端口调整对照（默认值见 thingsboard.yml）：

参数	默认值	修改后	服务
`HTTP_BIND_PORT`	8080	18080	Edge Web UI / HTTP 设备 API
`MQTT_BIND_PORT`	1883	11883	MQTT 设备接入
`COAP_BIND_PORT`	5683	15683	CoAP 设备接入（含 DTLS 5684 及后续端口段）
`LWM2M_ENABLED`	—	false	关闭 LwM2M 接入以避免端口冲突
`SNMP_ENABLED`	—	false	关闭 SNMP 接入
`INTEGRATIONS_RPC_PORT`	9090	19090	Edge 与远程集成执行器（Integration Executor）之间的 RPC

务必确认端口 18080、11883 以及 15683–15688 未被其他应用占用。其中 15683–15688 覆盖 CoAP 主端口（15683）、CoAP DTLS（15684）以及 LwM2M 的 5685–5688 对应的映射端口段；若 LwM2M 被禁用，则该段仅涉及 CoAP 相关端口。修改完成后，Edge Web UI 的访问地址也随之变为http://localhost:18080。

Step 5. 运行安装脚本

配置完成后，执行 Edge 自带的安装脚本完成数据库 schema 初始化与默认数据安装：

sudo /usr/share/tb-edge/bin/install/install.sh

该脚本负责创建/升级 ThingsBoard Edge 本地数据库表结构并写入系统级默认数据（角色、租户结构等），是首次启动前的必要步骤。

Step 6. 启动 ThingsBoard Edge 服务

sudo service tb-edge start

启动后可用以下命令确认运行状态与日志：

sudo service tb-edge status # 或查看日志（路径因发行包而异，通常位于 /var/log/tb-edge/）

Step 7. 打开 ThingsBoard Edge UI 并登录

服务启动后，打开 Edge Web 界面：

默认地址：http://localhost:8080
若你在第 4 步修改了 HTTP 绑定端口：http://localhost:18080

使用云服务器（ThingsBoard Server 或 ThingsBoard Cloud）上的租户凭据登录——这是 Edge 与云共享同一套租户体系的设计使然：Edge 通过CLOUD_RPC_HOST / CLOUD_RPC_PORT与云建立 gRPC 长连接并同步数据，UI 登录验证也复用云的租户账户体系。

与 Docker / CentOS 安装方式的对照

仓库在同一目录下还提供了另外两种安装指南，可互为参照：

Docker 方式：install/docker/instructions.md：通过docker compose启动thingsboard/tb-edge-pe镜像与postgres:16容器，使用 in-memory 队列 + SQL 数据库，环境变量形式与 .deb 方式一一对应（CLOUD_ROUTING_KEY、CLOUD_RPC_HOST等）。
CentOS/RHEL 方式：install/centos/instructions.md：使用dnf安装java-25-openjdk与postgresql16，以.rpm包（rpm -Uvh tb-edge-${TB_EDGE_TAG}pe.rpm）安装 Edge，并额外包含将pg_hba.conf中 IPv4 本地认证从ident改为md5的步骤。

两者在 Step 4/5/6/7 的配置参数与启动流程上与 Ubuntu 版完全一致，说明云边连接参数（CLOUD_RPC_*、CLOUD_ROUTING_*）在所有安装方式下都是统一的接口契约。

常见问题排查

端口冲突：若与 ThingsBoard Server 同机部署且未修改端口，启动时会因8080、1883、5683等被占用而失败。按第 4 步"更新绑定端口"一节调整即可。
云边无法连接：确认CLOUD_RPC_HOST可从 Edge 所在机器访问，且云服务器7070端口（默认CLOUD_RPC_PORT）在网络层面可达；若CLOUD_RPC_SSL_ENABLED=true，还需确保 SSL 证书配置正确。
数据库连接失败：核对SPRING_DATASOURCE_URL / USERNAME / PASSWORD三者的值，并确认 PostgreSQL 已启动、tb_edge库已创建（sudo service postgresql status）。
Java 版本不符：用java -version确认默认 JVM 为 25.x；如系统存在多版本，通过update-alternatives --config java切换。

总结

本指南对应的 Ubuntu 安装文档是 ThingsBoard Edge 在 Ubuntu 上从零部署的官方快路径：OpenJDK 25 → PostgreSQL 16 + tb_edge 库 → .deb 安装 → 云边参数与端口配置 → install.sh 初始化 → 启动服务 → 租户凭据登录。每个配置占位符均由服务器端 DefaultEdgeInstallInstructionsService 按当前 Edge 实例与服务器配置动态渲染，而端口默认值与云边 RPC 参数均可在 thingsboard.yml 中追溯到具体定义，为排障与二次配置提供了完整依据。