3、单机部署：ThingsBoard安装包获取、配置文件详解、启动与验证、日志查看

好，咱们进入第三章。这一章我打算手把手带你走一遍单机部署的全流程。说实话，单机部署是后面所有集群部署的基础，你把这个搞明白了，后面那些分布式的东西理解起来会轻松很多。

很多新手一上来就想着搞集群，结果连单机都跑不顺，排查问题的时候一脸懵。我个人习惯是，先老老实实把单机玩透，再去碰那些花里胡哨的架构。

3.1 安装包获取：别下错版本

ThingsBoard的安装包获取，其实就两个渠道：官方GitHub Releases和Docker Hub。我建议你优先用GitHub Releases，因为你能看到每个版本的Release Notes，知道修了什么Bug、加了什么功能。

官方下载地址：

  • GitHub Releases：https://github.com/thingsboard/thingsboard/releases
  • Docker Hub：https://hub.docker.com/r/thingsboard/tb-node

这里有个坑，我踩过。有一次我图省事，直接拉了个latest标签的Docker镜像，结果发现跟我的PostgreSQL版本不兼容，折腾了半天。后来我学乖了，永远指定具体版本号。

避坑指南： 我曾经在生产环境直接用了latest标签，第二天官方发了个新版本，自动更新后导致部分设备数据上报格式变了，差点出事故。从此以后，我所有生产环境都锁定版本号。

对于Linux单机部署，我推荐下载thingsboard-3.6.2.deb（Ubuntu/Debian）或thingsboard-3.6.2.rpm（CentOS/RHEL）。Windows版本也有，但我不建议在生产环境用Windows跑ThingsBoard，你想想看，Windows的稳定性跟Linux比还是有差距的。

3.2 配置文件详解：核心就这几个

安装包拿到手，下一步就是配置。ThingsBoard的配置文件主要分布在两个地方：

  • /etc/thingsboard/conf/ — 主配置目录
  • /usr/share/thingsboard/conf/ — 一些默认模板

咱们重点看/etc/thingsboard/conf/thingsboard.yml，这是核心中的核心。我把它拆成几个关键块来讲。

3.2.1 数据库配置

ThingsBoard支持PostgreSQL和Cassandra。单机部署我强烈建议用PostgreSQL，简单、稳定、好维护。Cassandra虽然性能好，但单机部署有点大材小用，而且运维成本高。

# thingsboard.yml 数据库部分
database:
  type: "postgres"  # 可选 postgres 或 cassandra
  ts:
    type: "sql"     # 时序数据存储类型，sql 或 cassandra
  
  entities:
    type: "sql"     # 实体数据存储类型
  
  # PostgreSQL 连接配置
  postgres:
    host: "localhost"
    port: 5432
    database: "thingsboard"
    username: "tb_user"
    password: "tb_password"
    maxPoolSize: 10

嗯，这里要注意maxPoolSize。我见过有人设成100，结果数据库连接池爆了，应用直接挂掉。单机部署，10到20个连接完全够用，别贪多。

3.2.2 队列配置

ThingsBoard内部用队列来解耦各个组件。单机部署默认用内存队列，够用了。但如果你要搞高可用，就得换成Kafka或RabbitMQ。

# 队列配置
queue:
  type: "in-memory"  # 单机用 in-memory，集群用 kafka 或 rabbitmq
  
  # 如果要用 Kafka
  kafka:
    bootstrap.servers: "localhost:9092"
    replication.factor: 1

我个人习惯是，单机部署一律用in-memory，少一个中间件就少一个故障点。等后面做集群了，再切到Kafka。

3.2.3 传输协议配置

ThingsBoard支持MQTT、HTTP、CoAP三种协议。默认都开着，但你可以按需关闭。

# 传输协议配置
transport:
  mqtt:
    enabled: true
    bind_address: "0.0.0.0"
    bind_port: 1883
    ssl:
      enabled: false
  
  http:
    enabled: true
    bind_address: "0.0.0.0"
    bind_port: 8080
  
  coap:
    enabled: true
    bind_address: "0.0.0.0"
    bind_port: 5683

这里有个安全建议：如果只是内部使用，MQTT的bind_address别设成0.0.0.0，改成内网IP，避免暴露到公网。我曾经帮一个客户排查问题，发现他的MQTT端口直接暴露在公网上，被扫到了，结果被人用来发垃圾数据。

3.2.4 其他关键配置

配置项 默认值 说明
server.port 8080 Web UI和API端口
server.ssl.enabled false 是否启用HTTPS
security.jwt.tokenExpirationTime 3600 JWT Token过期时间（秒）
logging.level INFO 日志级别，调试时可改为DEBUG
小技巧： 调试阶段可以把logging.level改成DEBUG，能看到更多细节。但生产环境一定要改回INFO，否则日志量会大到吓人，磁盘很快就满了。

3.3 启动与验证：三步走

配置改好了，咱们来启动。我习惯分三步走：启动服务、检查进程、验证API。

3.3.1 启动服务

如果你用的是deb包安装，启动命令很简单：

# 启动 ThingsBoard 服务
sudo systemctl start thingsboard

# 设置开机自启
sudo systemctl enable thingsboard

# 查看启动状态
sudo systemctl status thingsboard

如果是手动解压的tar包，那就用：

# 进入安装目录
cd /usr/share/thingsboard

# 启动（前台运行，方便看日志）
sudo ./bin/thingsboard start

# 或者后台运行
sudo nohup ./bin/thingsboard start > /var/log/thingsboard/startup.log 2>&1 &

我第一次部署时，直接用了./bin/thingsboard start，然后关掉了终端，结果服务也跟着停了。后来才意识到要用nohup或者systemd。嗯，这都是经验教训。

3.3.2 检查进程和端口

服务启动后，先确认进程是否在跑：

# 检查进程
ps aux | grep thingsboard

# 检查端口（默认8080）
netstat -tlnp | grep 8080

如果看到java进程在监听8080端口，说明启动成功了。如果没看到，别急，先去看日志。

3.3.3 验证API

进程跑起来了，但服务是不是真的可用？我习惯用curl验证一下：

# 验证Web UI是否可访问
curl -v http://localhost:8080

# 验证API是否正常
curl -X GET http://localhost:8080/api/noauth/health

如果返回{"status":"UP"}，恭喜你，ThingsBoard跑起来了。这时候打开浏览器，输入http://你的服务器IP:8080，应该能看到登录页面。

默认登录账号： 系统管理员 sysadmin@thingsboard.org / sysadmin，租户管理员 tenant@thingsboard.org / tenant。第一次登录后记得改密码。

3.4 日志查看：排查问题的利器

服务跑起来了，但万一出问题怎么办？日志就是你的第一道防线。ThingsBoard的日志默认在/var/log/thingsboard/目录下。

3.4.1 日志文件结构

日志文件 说明
thingsboard.log 主日志文件，记录所有INFO及以上级别的日志
thingsboard-error.log 错误日志，只记录ERROR级别
startup.log 启动日志，记录启动过程中的信息
audit.log 审计日志，记录用户操作（需开启审计功能）

3.4.2 常用日志查看命令

我平时排查问题，最常用的就是这几个命令：

# 实时查看最新日志（类似 tail -f）
sudo journalctl -u thingsboard -f

# 或者直接看日志文件
sudo tail -f /var/log/thingsboard/thingsboard.log

# 只看错误日志
sudo tail -f /var/log/thingsboard/thingsboard-error.log

# 搜索特定关键词（比如某个设备ID）
sudo grep "设备ID" /var/log/thingsboard/thingsboard.log

# 查看最近100行日志
sudo tail -100 /var/log/thingsboard/thingsboard.log

3.4.3 常见启动失败原因

我总结了几种最常见的启动失败情况，你遇到了可以直接对照排查：

  • 数据库连接失败：日志里会出现Connection refused或FATAL: database "thingsboard" does not exist。解决方法：检查PostgreSQL是否启动，数据库和用户是否创建。
  • 端口被占用：日志里出现Address already in use。解决方法：用netstat -tlnp | grep 8080找到占用端口的进程，杀掉或者改ThingsBoard的端口。
  • Java版本不对：日志里出现Unsupported major.minor version。解决方法：检查Java版本，ThingsBoard 3.x需要Java 11以上。
  • 内存不足：日志里出现OutOfMemoryError。解决方法：调整JVM参数，在/etc/thingsboard/conf/thingsboard.yml中增加-Xmx1g -Xms1g。
重要提醒： 我曾经遇到一个情况，日志里没有任何错误，但服务就是起不来。后来发现是磁盘空间满了，ThingsBoard在启动时需要写一些临时文件。所以，部署前一定检查磁盘空间，至少留5GB以上。

好了，单机部署这一套流程走下来，你应该能顺利把ThingsBoard跑起来了。下一章咱们聊聊数据迁移和备份，这可是运维的必修课，别错过。

← 上一章 📖 返回目录 下一章 →