1. Thingsboard本地部署Docker启动-Macos环境准备

在MacOS上部署Thingsboard前，需要确保系统满足以下基础条件。我的2019款MacBook Pro（Intel芯片）运行Monterey 12.6系统时，曾因Docker虚拟化支持问题导致安装失败，后来通过以下配置成功解决：

系统要求核查清单：

• macOS 10.15 Catalina或更高版本（建议使用最新稳定版）
• 至少4GB内存（实际生产环境推荐8GB+）
• 20GB可用磁盘空间（用于存放Docker镜像和数据库）
• 已安装Homebrew包管理器

重要提示：M1/M2芯片Mac需确认Docker Desktop已适配ARM架构，否则可能遇到镜像兼容性问题。我测试时发现部分x86镜像需要手动添加 --platform linux/amd64 参数才能正常运行。

1.1 Docker Desktop安装与配置

从Docker官网下载适配Mac的Docker Desktop安装包时，要注意版本选择：

# 通过Homebrew安装更便捷（推荐）
brew install --cask docker

安装完成后需要特别处理以下配置项：

1. 资源分配 ：在Preferences -> Resources中

   • CPUs：建议分配50%系统核心数（我的6核分配了3核）
   • Memory：最少4GB（复杂业务场景建议6GB+）
   • Swap：设置为1GB

2. 磁盘镜像位置 ：默认在 /Users/<username>/Library/Containers/com.docker.docker ，空间不足时可使用软链接转移到外置存储：

mv ~/Library/Containers/com.docker.docker /Volumes/External/Do
ln -s /Volumes/External/Do ~/Library/Containers/com.docker.docker

3. Daemon配置 ：在 ~/.docker/daemon.json 中添加国内镜像源加速下载：

{
  "registry-mirrors": [
    "https://docker.mirrors.ustc.edu.cn",
    "https://hub-mirror.c.163.com"
  ]
}

1.2 验证Docker环境

运行诊断命令确保组件正常工作：

# 检查Docker版本
docker --version
# 输出示例：Docker version 24.0.2, build cb74dfc

# 测试基础功能
docker run --rm hello-world

常见启动问题解决方案：

• "Virtualization support not detected" ：在终端执行：

  sysctl -a | grep machdep.cpu.features
  

  确认输出包含 VMX 标志。如果没有，需要：

  1. 重启按住Command+R进入恢复模式
  2. 打开终端执行： csrutil disable
  3. 重启后再次尝试

• 端口冲突 ：Thingsboard默认使用8080端口，检查占用情况：

  lsof -i :8080
  

2. Thingsboard Docker部署方案解析

2.1 官方镜像选择策略

Thingsboard提供多个Docker镜像变体，根据我的测试经验推荐：

镜像类型	适用场景	内存消耗	启动速度
thingsboard/tb-postgres	开发测试	中等	快
thingsboard/tb-cassandra	生产环境	高	慢
thingsboard/tb	自定义部署	可变	取决于配置

对于Mac本地开发，建议选择 tb-postgres 版本，因为：

1. Postgres比Cassandra更轻量
2. 单容器包含所有依赖，调试方便
3. 数据持久化方案简单

2.2 容器编排方案设计

虽然官方推荐docker-compose，但在Mac上我发现单容器部署更易管理。以下是优化后的部署架构：

MacOS Host
├── Docker Desktop
│   └── Thingsboard Container
│       ├── Postgres (内嵌)
│       ├── Zookeeper (内嵌)
│       └── Kafka (内嵌)
└── 数据卷
    ├── tb-data → /data
    └── tb-logs → /var/log/thingsboard

这种设计的优势：

• 避免多容器通信开销
• 日志集中管理
• 数据备份只需处理单个卷

3. 详细部署步骤实录

3.1 拉取镜像并初始化

使用以下命令获取最新镜像：

docker pull thingsboard/tb-postgres:latest

首次启动时需要执行数据库初始化：

docker run -it -p 8080:8080 -p 1883:1883 \
  -v ~/tb-data:/data \
  -v ~/tb-logs:/var/log/thingsboard \
  --name my-thingsboard \
  thingsboard/tb-postgres:latest \
  install \
  --loadDemo

关键参数说明：

• -p 8080:8080 ：映射HTTP端口
• -p 1883:1883 ：MQTT协议端口
• --loadDemo ：加载演示数据（首次安装必选）

实测发现：在Mac上首次初始化可能需要5-10分钟，控制台没有输出时不要中断进程！

3.2 常规运行命令

初始化完成后，使用以下命令正常启动：

docker start my-thingsboard

查看实时日志：

docker logs -f my-thingsboard

3.3 系统配置调优

修改 /data/thingsboard/conf/thingsboard.yml 中的关键参数：

server:
  address: 0.0.0.0
  port: 8080
  ssl:
    enabled: false

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/thingsboard
    username: postgres
    password: postgres

MacOS特有优化项：

1. 增加JVM堆内存限制：

   docker update my-thingsboard --memory 2g --memory-swap 3g
   

2. 禁用IPv6（减少日志警告）：

   docker exec -it my-thingsboard sysctl -w net.ipv6.conf.all.disable_ipv6=1
   

4. 部署后配置与验证

4.1 访问控制台

在浏览器打开：

http://localhost:8080

使用默认凭证登录：

• 用户名：tenant@thingsboard.org
• 密码：tenant

安全提示：首次登录后立即修改密码！我在测试时曾因使用默认密码导致被入侵。

4.2 服务状态检查

通过API验证服务健康状态：

curl -X GET "http://localhost:8080/api/v1/admin/health"

预期返回：

{
  "status": "healthy",
  "database": {
    "status": "up",
    "error": null
  }
}

4.3 数据持久化验证

测试数据存储功能：

1. 创建测试设备
2. 重启容器
3. 检查设备是否存在

执行命令验证Postgres数据卷：

docker exec -it my-thingsboard psql -U postgres -d thingsboard -c "SELECT COUNT(*) FROM device;"

5. 常见问题解决方案

5.1 端口冲突处理

如果8080端口被占用，可以改用其他端口：

docker run -p 8090:8080 ... # 修改第一个端口号为可用端口

查询端口占用进程：

lsof -i :8080

5.2 容器启动失败排查

查看完整错误日志：

docker inspect my-thingsboard --format='{{.State.Error}}'

常见错误及修复：

1. 数据库连接失败 ：

   Caused by: org.postgresql.util.PSQLException: Connection refused
   

   解决方案：检查Postgres是否正常启动，执行：

   docker exec -it my-thingsboard service postgresql status
   

2. 内存不足 ：

   java.lang.OutOfMemoryError: Java heap space
   

   增加JVM参数：

   docker update my-thingsboard -e JAVA_OPTS="-Xms1g -Xmx2g"
   

5.3 性能优化技巧

基于实际使用经验总结的MacOS专属优化：

1. Docker磁盘性能 ：

   docker system prune -a --volumes
   

   定期清理无用镜像可提升I/O速度

2. 网络模式选择 ：

   docker run --network=host ...
   

   在开发环境使用host网络模式可减少NAT开销

3. 日志轮转配置 ： 修改 /data/thingsboard/conf/logback.xml ：

   <maxHistory>7</maxHistory>
   <totalSizeCap>1GB</totalSizeCap>
   

6. 生产环境进阶配置

6.1 数据备份方案

创建自动化备份脚本 backup.sh ：

#!/bin/bash
BACKUP_DIR=~/tb-backups
mkdir -p $BACKUP_DIR
docker exec my-thingsboard pg_dump -U postgres thingsboard > $BACKUP_DIR/tb-$(date +%Y%m%d).sql

设置定时任务（每天2点执行）：

crontab -e
# 添加：
0 2 * * * /bin/bash ~/backup.sh

6.2 HTTPS配置

使用Let's Encrypt证书的配置示例：

server:
  ssl:
    enabled: true
    key-store: /data/keys/tb-keystore.p12
    key-store-password: yourpassword
    key-store-type: PKCS12

生成证书的命令：

openssl pkcs12 -export -in fullchain.pem -inkey privkey.pem -out /data/keys/tb-keystore.p12

6.3 集群部署考虑

虽然Mac本地环境通常单机运行，但了解集群配置有助于后期迁移：

# docker-compose-cluster.yml
version: '3'
services:
  tb1:
    image: thingsboard/tb
    environment:
      TB_QUEUE_TYPE: kafka
      SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard
    depends_on:
      - postgres
      - zookeeper
      - kafka

关键配置点：

• 使用外部数据库
• 消息队列改为Kafka
• 共享配置中心

7. 开发调试技巧

7.1 热部署配置

在开发模式下启用自动重启：

docker run -e SPRING_DEVTOOLS_RESTART_ENABLED=true ...

7.2 远程调试

启用JPDA调试端口：

docker run -e JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005" \
  -p 5005:5005 ...

IntelliJ IDEA连接配置：

1. Run → Edit Configurations → Add Remote JVM Debug
2. Host: localhost, Port: 5005

7.3 自定义插件开发

创建插件开发环境：

mkdir -p ~/tb-plugins && cd ~/tb-plugins
docker run -v $(pwd):/plugins thingsboard/tb-postgres

插件热加载配置：

thingsboard:
  plugins:
    runtime: development
    directory: /plugins