2. ThingsBoard 安装与部署：单机安装（Docker 方式）、配置数据库（PostgreSQL/Cassandra）、初始配置与管理员设置
本章聚焦于 ThingsBoard 单机生产环境的快速搭建。采用 Docker Compose 编排方式，能够将 ThingsBoard 核心服务、数据库及消息队列一键化部署。你将掌握从环境准备、数据库选型（PostgreSQL 与 Cassandra 的适用场景）、到首次登录与管理员初始化的完整流程。
2.1 部署架构概览
单机部署模式下，ThingsBoard 将以下核心组件运行在同一台物理机或虚拟机上：
- ThingsBoard 核心服务：提供 REST API、WebSocket、规则引擎及设备连接网关。
- 数据库层：PostgreSQL 用于存储实体元数据、用户、仪表板配置；Cassandra 用于存储时序数据（遥测数据）。
- 消息队列：Kafka 或 RabbitMQ，用于异步处理设备数据与规则链事件。
- 缓存：Redis，用于会话管理与高频数据缓存。
架构要点： 单机部署适合设备量 ≤ 1000 台、每秒消息数 ≤ 500 的初期场景。当设备规模增长时，可将数据库与消息队列分离至独立服务器，实现水平扩展。
2.2 环境准备与前置条件
在开始部署前，请确保主机满足以下最低配置要求：
| 资源项 | 最低要求 | 推荐配置 |
|---|---|---|
| CPU | 2 核 | 4 核及以上 |
| 内存 | 4 GB | 8 GB（含 Cassandra 时建议 16 GB） |
| 磁盘 | 20 GB 可用空间 | 50 GB SSD |
| 操作系统 | Ubuntu 20.04 / CentOS 7+ | Ubuntu 22.04 LTS |
| Docker | v20.10+ | v24.0+ |
| Docker Compose | v2.0+ | v2.20+ |
检查 Docker 环境： 执行
docker --version 与 docker compose version 确认已安装。若未安装，请参考 Docker 官方文档完成安装。
2.3 数据库选型：PostgreSQL vs Cassandra
ThingsBoard 支持两种数据库组合方案，选择取决于你的数据存储需求：
| 对比维度 | PostgreSQL（单库模式） | PostgreSQL + Cassandra（混合模式） |
|---|---|---|
| 元数据存储 | PostgreSQL | PostgreSQL |
| 时序数据存储 | PostgreSQL（ts_kv 表） | Cassandra |
| 写入吞吐量 | 中等（≤ 500 msg/s） | 高（≥ 5000 msg/s） |
| 磁盘空间占用 | 较低 | 较高（需预分配空间） |
| 运维复杂度 | 低 | 中（需管理 Cassandra 集群） |
| 推荐场景 | 开发测试、小规模生产 | 大规模生产、高频率数据采集 |
注意： 生产环境中，一旦选定数据库方案并写入数据后，切换数据库类型需要迁移数据，操作复杂。建议在部署前根据设备量与消息频率做出选择。
2.4 Docker Compose 部署步骤
以下步骤以 PostgreSQL + Cassandra 混合模式 为例，这是生产环境最常用的配置。
步骤 1：获取 Docker Compose 配置文件
从 ThingsBoard 官方 GitHub 仓库克隆或下载对应版本的 Docker Compose 文件：
# 创建部署目录
mkdir -p ~/thingsboard-deploy && cd ~/thingsboard-deploy
# 下载适用于 PostgreSQL + Cassandra 的 docker-compose.yml
wget https://raw.githubusercontent.com/thingsboard/thingsboard/master/docker/docker-compose.yml
# 下载环境变量模板
wget https://raw.githubusercontent.com/thingsboard/thingsboard/master/docker/.env步骤 2：配置环境变量
编辑 .env 文件，设置关键参数：
# ThingsBoard 版本
TB_VERSION=3.6.1
# PostgreSQL 配置
POSTGRES_USER=postgres
POSTGRES_PASSWORD=your_strong_password
POSTGRES_DB=thingsboard
# Cassandra 配置
CASSANDRA_HOST=cassandra
CASSANDRA_PORT=9042
# 时区设置
TZ=Asia/Shanghai步骤 3：启动服务
# 启动所有容器（后台运行）
docker compose up -d
# 查看启动日志
docker compose logs -f thingsboard首次启动时，ThingsBoard 会自动初始化数据库表结构。等待约 2-5 分钟，直到日志中出现 Started ThingsBoard Server 字样。
步骤 4：验证服务状态
# 检查所有容器运行状态
docker compose ps
# 预期输出示例：
# NAME IMAGE STATUS
# thingsboard thingsboard/tb:3.6.1 Up (healthy)
# postgres postgres:15 Up (healthy)
# cassandra cassandra:4.1 Up (healthy)
# redis redis:7-alpine Up (healthy)2.5 初始配置与管理员设置
服务启动成功后，通过浏览器访问 http://<服务器IP>:8080 进入 ThingsBoard 登录页面。
默认管理员账户
| 角色 | 用户名 | 默认密码 |
|---|---|---|
| 系统管理员 | sysadmin@thingsboard.org | sysadmin |
| 租户管理员 | tenant@thingsboard.org | tenant |
安全警告： 首次登录后，请立即修改默认密码。建议使用至少 12 位包含大小写字母、数字和特殊字符的强密码。
修改管理员密码
- 使用
sysadmin@thingsboard.org/sysadmin登录。 - 点击右上角用户头像 → Account → Change password。
- 输入当前密码，设置新密码并确认。
- 点击 Save 完成修改。
配置邮件服务器（可选）
为支持用户注册、密码重置等功能，建议配置 SMTP 邮件服务：
- 进入 System Settings → Mail。
- 填写 SMTP 主机、端口、用户名、密码。
- 点击 Send test email 验证配置是否正确。
2.6 常见问题与排错
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 容器启动后立即退出 | 端口冲突（8080 被占用） | 修改 docker-compose.yml 中端口映射，如 8080:9090 |
| 数据库连接失败 | PostgreSQL 或 Cassandra 未就绪 | 等待 30 秒后重试，或检查 docker compose logs postgres |
| 登录页面无法访问 | 防火墙未放行 8080 端口 | 执行 sudo ufw allow 8080 或配置云安全组 |
| 时序数据写入缓慢 | Cassandra 堆内存不足 | 在 .env 中增加 CASSANDRA_HEAP_SIZE=2G |
快速诊断命令： 使用
docker compose logs --tail=50 -f thingsboard 实时查看 ThingsBoard 日志，错误信息通常会直接指出问题根源。
2.7 本章小结
通过 Docker Compose 方式，你已成功完成 ThingsBoard 的单机部署，并掌握了以下关键技能：
- 理解单机部署的组件架构与数据流向。
- 根据业务规模选择 PostgreSQL 单库或 PostgreSQL + Cassandra 混合模式。
- 使用 Docker Compose 一键启动 ThingsBoard 及其依赖服务。
- 完成管理员账户的初始化与安全配置。
下一阶段，你将学习如何连接真实设备、创建仪表板以及配置规则链，将 ThingsBoard 从“安装完成”推进到“实际可用”。