开源项目部署环境配置指南：多环境部署方案与生产环境配置实践

部署方案决策指南：选择最适合你的方式

在开始部署ThingsBoard之前，通过以下决策树快速定位最适合你的部署方案：

开发测试场景 → 选择Docker容器部署（5-10分钟完成，资源占用率低）
生产环境场景 → 选择二进制包部署（稳定性高，维护成本适中）
二次开发场景 → 选择源码编译部署（高度定制化，灵活性强）

硬件资源参考表

部署规模	CPU核心	内存	存储	推荐部署方式
开发测试	2核	4GB	20GB HDD	Docker容器
小型生产	4核	8GB	40GB SSD	二进制包
大型生产	8核+	16GB+	100GB+ SSD	源码编译+集群

方案一：Docker容器部署——快速搭建开发测试环境

环境预检清单

• Docker Engine 20.10+ 和 Docker Compose 2.0+
• 至少2GB可用磁盘空间
• 网络连接（用于拉取镜像）

实施步骤

1. 安装Docker环境

# Ubuntu系统安装Docker
sudo apt update && sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update && sudo apt install -y docker-ce docker-compose-plugin
sudo systemctl enable --now docker

2. 获取项目代码并初始化

git clone https://gitcode.com/GitHub_Trending/th/thingsboard
cd thingsboard/docker
chmod +x docker-create-log-folders.sh docker-install-tb.sh
./docker-create-log-folders.sh  # 创建日志目录结构

3. 启动服务集群

# 加载演示数据启动（首次部署推荐）
./docker-install-tb.sh --loadDemo

# 启动所有服务组件
docker compose up -d

验证方法

1. 检查服务状态：docker compose ps，确保所有服务状态为"Up"
2. 访问Web界面：http://服务器IP:8080
3. 使用默认凭据登录：[e-mail] / sysadmin

⚠️ 注意：Docker部署默认使用嵌入式H2数据库，不适合生产环境长期使用

方案二：二进制包部署——构建生产级稳定环境

环境预检清单

• JDK 11+ 运行环境
• PostgreSQL 12+ 或 Cassandra 3.11+ 数据库
• 系统服务管理工具（systemd或sysvinit）

实施步骤

1. 准备数据库环境

# PostgreSQL安装与配置
sudo apt install -y postgresql postgresql-contrib
sudo -u postgres psql -c "CREATE DATABASE thingsboard;"
sudo -u postgres psql -c "CREATE USER thingsboard WITH PASSWORD 'thingsboard';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE thingsboard TO thingsboard;"

2. 生成并安装二进制包

git clone https://gitcode.com/GitHub_Trending/th/thingsboard
cd thingsboard/packaging/java/scripts
chmod +x install.sh
sudo ./install.sh  # 生成并安装deb包

3. 配置数据库连接

# 编辑主配置文件
sudo nano /etc/thingsboard/thingsboard.yml

# 修改数据库连接部分
spring:
  datasource:
    driverClassName: org.postgresql.Driver
    url: jdbc:postgresql://localhost:5432/thingsboard
    username: thingsboard
    password: thingsboard

4. 启动服务并设置开机自启

sudo systemctl daemon-reload
sudo systemctl enable thingsboard
sudo systemctl start thingsboard

验证方法

1. 检查服务状态：sudo systemctl status thingsboard
2. 查看应用日志：tail -f /var/log/thingsboard/thingsboard.log
3. 访问Web界面：http://服务器IP:8080

💡 提示：生产环境建议配置Nginx作为反向代理，并启用HTTPS加密

方案三：源码编译部署——定制化开发环境搭建

环境预检清单

• JDK 17+ 开发环境
• Maven 3.8+ 构建工具
• Node.js 16+ 和 Yarn 包管理器
• 至少4GB内存（编译过程需要）

实施步骤

1. 安装基础依赖

# 安装JDK和Maven
sudo apt install -y openjdk-17-jdk maven

# 安装Node.js和Yarn
curl -fsSL https://deb.nodesource.com/setup_16.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g yarn

2. 获取代码并编译

git clone https://gitcode.com/GitHub_Trending/th/thingsboard
cd thingsboard

# 编译后端代码
mvn clean install -DskipTests -Dmaven.javadoc.skip=true

# 编译前端UI
cd ui-ngx
yarn install
yarn build
cd ..

3. 配置与启动

# 复制配置文件模板
cd application/src/main/resources
cp thingsboard.yml.dist thingsboard.yml

# 编辑数据库配置（同上二进制部署步骤）

# 启动服务
cd ../../../target/bin
./thingsboard.sh start

验证方法

1. 检查服务日志：tail -f logs/thingsboard.log
2. 验证API可用性：curl http://localhost:8080/api/v1/health
3. 访问Web界面：http://服务器IP:8080

部署后必做的5项安全配置

1. 更改默认管理员密码

登录系统后立即修改默认密码：

1. 点击右上角用户头像 → "Profile"
2. 选择"Change password"
3. 设置强密码（至少8位，包含大小写字母、数字和特殊符号）

2. 配置HTTPS加密

# 使用Let's Encrypt获取证书
sudo apt install certbot
sudo certbot certonly --standalone -d your-domain.com

# 配置Nginx反向代理（/etc/nginx/sites-available/thingsboard）
server {
    listen 443 ssl;
    server_name your-domain.com;
    
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;
    
    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

3. 限制数据库访问权限

-- 仅允许应用服务器访问数据库
ALTER ROLE thingsboard WITH CONNECTION LIMIT 10;
REVOKE ALL ON SCHEMA public FROM public;
GRANT USAGE ON SCHEMA public TO thingsboard;

4. 配置防火墙规则

# 只开放必要端口
sudo ufw allow 22/tcp    # SSH
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 1883/tcp  # MQTT
sudo ufw enable

5. 启用审计日志

编辑配置文件启用详细审计日志：

# /etc/thingsboard/thingsboard.yml
audit:
  enabled: true
  level: INFO
  log_credentials: false

场景化故障排除指南

场景一：服务启动失败，日志显示内存不足

现象：服务启动后立即退出，日志中有"OutOfMemoryError"

原因分析：默认JVM内存配置不适合当前环境

解决方案：

# 编辑环境变量配置
sudo nano /etc/thingsboard/conf/thingsboard.conf

# 修改JVM参数
export JAVA_OPTS="$JAVA_OPTS -Xms1024m -Xmx2048m"

# 重启服务
sudo systemctl restart thingsboard

场景二：设备无法连接，MQTT端口访问失败

现象：设备连接超时，日志无任何连接记录

原因分析：可能是防火墙阻止或服务未启用MQTT传输

解决方案：

# 检查MQTT服务状态
sudo systemctl status tb-mqtt-transport

# 如未启动，启用并启动服务
sudo systemctl enable tb-mqtt-transport
sudo systemctl start tb-mqtt-transport

# 开放MQTT端口
sudo ufw allow 1883/tcp

场景三：Web界面显示502错误

现象：访问页面显示"502 Bad Gateway"

原因分析：后端服务未运行或Nginx配置错误

解决方案：

# 检查ThingsBoard服务状态
sudo systemctl status thingsboard

# 检查Nginx配置
sudo nginx -t

# 查看应用日志
tail -f /var/log/thingsboard/thingsboard.log

部署自动化脚本示例

以下是一个简化的部署自动化脚本，适用于生产环境二进制部署：

#!/bin/bash
# thingsboard-deploy.sh - 自动化部署脚本

# 1. 安装依赖
sudo apt update && sudo apt install -y openjdk-11-jre postgresql

# 2. 配置数据库
sudo -u postgres psql -c "CREATE DATABASE thingsboard;"
sudo -u postgres psql -c "CREATE USER thingsboard WITH PASSWORD 'secure_password';"
sudo -u postgres psql -c "GRANT ALL PRIVILEGES ON DATABASE thingsboard TO thingsboard;"

# 3. 下载并安装
wget https://example.com/thingsboard.deb  # 替换为实际下载地址
sudo dpkg -i thingsboard.deb

# 4. 配置数据库连接
sudo sed -i 's/username:.*/username: thingsboard/' /etc/thingsboard/thingsboard.yml
sudo sed -i 's/password:.*/password: secure_password/' /etc/thingsboard/thingsboard.yml

# 5. 启动服务
sudo systemctl enable --now thingsboard

# 6. 验证部署
if curl -s http://localhost:8080/api/v1/health | grep -q "UP"; then
    echo "部署成功！"
else
    echo "部署失败，请检查日志。"
    exit 1
fi

使用方法：

chmod +x thingsboard-deploy.sh
sudo ./thingsboard-deploy.sh

部署方案演进路线图

随着业务增长，你的部署架构可能需要如下演进：

1. 初始阶段：单节点Docker部署 → 快速验证业务模型
2. 成长阶段：二进制包部署 + 独立数据库 → 提升稳定性
3. 扩展阶段：多节点集群 + 负载均衡 → 支持高并发
4. 成熟阶段：Kubernetes编排 + 自动扩缩容 → 企业级部署

以上告警监控界面展示了ThingsBoard的设备监控能力，通过正确部署和配置，你可以实时掌握设备状态和系统健康情况。选择适合当前阶段的部署方案，并随着业务发展逐步优化，是保障IoT平台稳定运行的关键。