1. 项目缘起为什么要在Windows上折腾ThingsBoard全家桶最近在做一个物联网数据中台的原型验证需要快速搭建一个能接入多种协议设备、具备数据可视化和管理能力的平台。ThingsBoard这个开源物联网平台自然就进入了视线。它功能齐全社区活跃用起来确实香。但团队的主力开发环境清一色都是Windows直接上Linux服务器部署虽然正统但开发调试、本地验证就变得很麻烦。所以一个很实际的需求就摆在了面前能不能在Windows本地用最轻量的方式把ThingsBoard核心服务和它的网关ThingsBoard Gateway一起跑起来方便我们做前期的协议对接、数据流测试和规则链调试答案当然是肯定的而且Docker就是解决这个问题的“瑞士军刀”。通过Docker Desktop for Windows我们可以在Windows上创建一个轻量的Linux虚拟机环境来运行容器完美避开在Windows原生环境配置Java、PostgreSQL、Cassandra等一堆依赖的噩梦。整个过程就像是把一整套复杂的Linux服务“打包”成一个即开即用的应用程序在Windows上双击运行。这篇内容我就来详细拆解一下从零开始在Windows 10/11系统上使用Docker部署ThingsBoard开源版Community Edition以及ThingsBoard Gateway的全过程。我会把每一步的操作意图、背后的原理、以及我踩过的那些坑都讲清楚目标是让你看完之后能在自己的电脑上一次性成功搭建起这个物联网开发测试环境。2. 战前准备理清架构与备好“弹药”在动手敲命令之前我们必须先搞清楚我们要部署的东西到底是什么以及它们之间的关系。盲目操作只会导致容器启动了却连不上或者服务跑了却收不到数据。2.1 ThingsBoard核心服务架构浅析ThingsBoard本身不是一个单一的软件它是一组协同工作的微服务。对于开源版最核心的几个组件是ThingsBoard主服务提供Web UI界面、REST API、规则引擎核心。它用Java编写是我们主要操作和访问的对象。数据库ThingsBoard需要存储设备元数据、用户信息、规则链配置等。开源版默认使用PostgreSQL作为关系型数据库。对于生产环境的海量遥测数据它推荐使用Cassandra或TimescaleDB但在开发测试阶段使用PostgreSQL存储所有数据是官方Docker镜像的默认且最简单的方式。缓存为了提升性能ThingsBoard使用Redis作为缓存服务。在Docker部署时我们通常会为这三个服务ThingsBoard, PostgreSQL, Redis各自启动一个容器并通过Docker网络让它们互联。2.2 ThingsBoard Gateway的角色定位ThingsBoard Gateway是一个独立的服务它的核心职责是协议转换和数据桥接。ThingsBoard主服务本身主要支持HTTP、CoAP、MQTT等标准物联网协议。但现实中很多设备可能使用Modbus、OPC UA、CAN、BMS私有协议等。直接让这些设备对接ThingsBoard主服务会很困难。这时Gateway就出场了。它部署在更靠近设备侧的网络中比如一台工控机或树莓派上负责通过相应的适配器Connector与各种异构设备通信采集数据。将采集到的数据统一转换成ThingsBoard能理解的格式通常是MQTT或HTTP协议。将转换后的数据上传到ThingsBoard主服务。所以在我们的本地测试环境中Gateway容器和ThingsBoard主容器是分开的它们通过MQTT协议进行通信。Gateway模拟了现场设备的接入行为。2.3 环境与工具清单准备好以下“弹药”接下来的操作会顺畅很多操作系统Windows 10 专业版/企业版/教育版版本2004及以上Build 19041及以上或 Windows 11。家庭版需要安装WSL2过程会稍复杂。Docker Desktop for Windows这是核心工具。确保安装时启用WSL2后端性能更好或Hyper-V。安装后务必在设置Settings 资源Resources中为Docker分配足够的内存建议至少4GB8GB更佳和CPU核心。终端工具Windows Terminal推荐或PowerShell。用于执行所有Docker命令。文本编辑器VS Code、Notepad等用于编辑配置文件。绝对不要用Windows自带的记事本它可能会在保存时修改文件编码如添加BOM头导致Linux容器内的应用读取配置出错。网络环境确保能正常访问Docker Hub镜像仓库。有时拉取镜像缓慢可以配置国内镜像加速器。提示在Docker Desktop设置中勾选“Expose daemon on tcp://localhost:2375 without TLS”通常不是必须的且可能带来安全风险保持默认即可。3. 核心战场使用Docker Compose一键部署ThingsBoard最优雅的部署方式无疑是使用Docker Compose。它通过一个YAML文件docker-compose.yml定义所有服务容器、它们的配置以及网络关系然后一条命令就能启动整个应用栈。3.1 编写Docker Compose配置文件在你的工作目录例如D:\thingsboard-demo下创建一个名为docker-compose.yml的文件。将以下内容复制进去我会逐段解释关键配置。version: 3.8 services: postgres: image: postgres:15-alpine container_name: tb-postgres restart: unless-stopped environment: POSTGRES_DB: thingsboard POSTGRES_PASSWORD: postgres volumes: - ./postgres-data:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U postgres] interval: 10s timeout: 5s retries: 5 networks: - tb-network redis: image: redis:7-alpine container_name: tb-redis restart: unless-stopped command: redis-server --appendonly yes volumes: - ./redis-data:/data healthcheck: test: [CMD, redis-cli, ping] interval: 10s timeout: 5s retries: 5 networks: - tb-network thingsboard: image: thingsboard/tb-postgres:latest container_name: tb-core restart: unless-stopped depends_on: postgres: condition: service_healthy redis: condition: service_healthy environment: TB_QUEUE_TYPE: in-memory SPRING_DATASOURCE_URL: jdbc:postgresql://postgres:5432/thingsboard SPRING_DATASOURCE_USERNAME: postgres SPRING_DATASOURCE_PASSWORD: postgres volumes: - ./thingsboard-data:/data - ./thingsboard-logs:/var/log/thingsboard - ./thingsboard-conf:/etc/thingsboard/conf ports: - 8080:9090 - 1883:1883 - 5683:5683/udp networks: - tb-network networks: tb-network: driver: bridge关键配置解读版本与网络version: 3.8声明Compose文件格式版本。我们创建了一个自定义的桥接网络tb-network三个服务都加入其中这样它们可以通过容器名如postgres直接相互访问无需知道IP地址。PostgreSQL服务image: postgres:15-alpine使用Alpine Linux版本的PostgreSQL 15镜像体积小。environment设置数据库名和密码。注意这是示例密码在生产环境中必须使用强密码volumes将容器内的数据目录映射到宿主机的./postgres-data文件夹。这样即使容器删除数据也不会丢失。healthcheck健康检查。ThingsBoard容器会等待PostgreSQL健康后才启动避免连接失败。Redis服务配置逻辑类似启用了AOF持久化--appendonly yes。ThingsBoard主服务image: thingsboard/tb-postgres:latest这是官方提供的、已集成PostgreSQL驱动和配置的镜像。如果你未来想用Cassandra镜像是thingsboard/tb-cassandra。depends_oncondition: service_healthy这是关键改进。它确保ThingsBoard容器只有在PostgreSQL和Redis都健康而不仅仅是启动后才启动避免了启动顺序导致的依赖问题。environmentTB_QUEUE_TYPE: in-memory设置规则引擎消息队列为内存模式。这是单机开发模式简单高效。集群模式需要配置Kafka或RabbitMQ。SPRING_DATASOURCE_*告诉ThingsBoard如何连接我们上面启动的PostgreSQL容器。注意主机名就是服务名postgres。ports端口映射。8080:9090将容器的9090端口ThingsBoard HTTP服务映射到宿主机的8080端口。这样我们就能通过http://localhost:8080访问Web UI。1883:1883MQTT协议端口用于设备或Gateway接入。5683:5683/udpCoAP协议端口UDP协议。volumes映射了数据、日志和配置目录方便我们查看日志和持久化配置。3.2 启动服务并完成初始化打开终端PowerShell或Windows Terminal导航到你的docker-compose.yml文件所在目录。执行启动命令docker-compose up -d-d参数表示在后台运行。Docker会开始拉取镜像首次运行并启动三个容器。查看容器状态docker-compose ps你应该看到三个容器的状态都是Up (healthy)或Up。ThingsBoard容器的启动需要一些时间1-2分钟来初始化数据库。监控ThingsBoard日志等待初始化完成docker-compose logs -f thingsboard使用-f参数可以实时跟踪日志。当你看到类似以下的日志时表示启动成功Started ThingsBoard Server Application in xx.xxx seconds (JVM running for xx.xxx)访问Web UI打开浏览器访问http://localhost:8080。你会看到ThingsBoard的登录页面。首次登录使用默认系统管理员账号登录。用户名sysadminthingsboard.org密码sysadmin登录后系统会强制你修改密码。请务必修改并牢记新密码。至此ThingsBoard核心平台就已经在你的Windows上运行起来了。你可以创建租户、设备、仪表盘体验基本功能了。4. 侧翼推进部署与配置ThingsBoard GatewayGateway是独立服务我们将为它单独准备配置和运行。4.1 创建Gateway配置文件目录在docker-compose.yml同级目录下创建一个新文件夹例如tb-gateway-config。这个文件夹将用来存放Gateway的配置文件并通过卷映射到容器内。进入tb-gateway-config文件夹创建Gateway的核心配置文件tb_gateway.yaml。内容如下server: # ThingsBoard主服务的地址和端口 address: tb-core port: 1883 # 从ThingsBoard Web UI创建设备后获取的Access Token accessToken: YOUR_DEVICE_ACCESS_TOKEN storage: # 存储类型file表示使用本地文件存储映射卷持久化 type: file # 数据存储目录 data_folder: ./data/ # 最大文件读取行数 max_file_count: 10 # 最大读取行数 max_read_records_count: 10 # 读取文件间隔秒 max_records_per_file: 10000 connectors: # 这里配置具体的协议连接器例如MQTT、Modbus等 # 我们先配置一个示例的MQTT连接器用于测试 - name: MQTT Broker Connector type: mqtt configuration: mqtt.json配置解读与注意事项server.address: 这里填的是tb-core即我们在Docker Compose中定义的ThingsBoard主服务的容器名。因为Gateway也会通过Docker Compose启动并加入同一个网络所以可以直接通过容器名访问。server.accessToken:这是关键这个Token不是随意写的它对应ThingsBoard平台上的一个设备。你需要登录ThingsBoard Web UI (http://localhost:8080)。进入“设备”页面创建一个新设备例如命名为 “Test_Gateway”。点击该设备进入详情复制其“访问令牌”Access Token。用复制的Token替换YOUR_DEVICE_ACCESS_TOKEN。Gateway将以此设备的身份向ThingsBoard上报数据。4.2 配置MQTT连接器示例为了测试Gateway的数据流我们在同一目录tb-gateway-config下创建一个MQTT连接器的配置文件mqtt.json。这个配置让Gateway扮演一个MQTT客户端去订阅一个公共的MQTT测试Broker并将收到的消息转发给ThingsBoard。{ broker: { name: Test MQTT Broker, host: test.mosquitto.org, port: 1883, security: { type: anonymous } }, mapping: [ { topicFilter: test/topic, converter: { type: json, deviceNameJsonExpression: ${sensorId}, deviceTypeJsonExpression: default, timeout: 60000, attributes: [ { type: string, key: model, value: ${model} } ], timeseries: [ { type: double, key: temperature, value: ${temp} }, { type: double, key: humidity, value: ${hum} } ] } } ], connectRequests: [], disconnectRequests: [], attributeRequests: [], attributeUpdates: [], serverSideRpc: [] }配置解读broker.host: 我们使用了公共的MQTT测试服务器test.mosquitto.org。Gateway会连接这个服务器。topicFilter: Gateway会订阅名为test/topic的主题。converter: 定义了如何将收到的MQTT消息JSON格式转换为ThingsBoard的设备属性和遥测数据。deviceNameJsonExpression: 从消息的JSON中提取sensorId字段的值作为设备名。这意味着如果消息{sensorId: Sensor01, temp: 25}Gateway会在ThingsBoard中创建或匹配一个名为 “Sensor01” 的设备。attributes和timeseries: 定义了哪些JSON字段映射为设备的静态属性如型号和动态遥测数据如温湿度。4.3 使用Docker运行Gateway我们不修改之前的docker-compose.yml而是为Gateway单独使用docker run命令这样更清晰。在终端中执行docker run -d --name tb-gateway --restart unless-stopped \ -v D:\thingsboard-demo\tb-gateway-config:/config \ --network thingsboard-demo_tb-network \ thingsboard/tb-gateway命令拆解-d: 后台运行。--name tb-gateway: 指定容器名称。--restart unless-stopped: 自动重启策略。-v D:\thingsboard-demo\tb-gateway-config:/config:这是最重要的一部分它将我们Windows主机上的配置文件目录映射到容器内的/config目录。Gateway容器启动时会自动加载/config/tb_gateway.yaml。请将D:\thingsboard-demo\tb-gateway-config替换为你实际的绝对路径。使用相对路径如./tb-gateway-config在docker run中有时会因上下文问题导致映射失败因此强烈建议使用绝对路径。--network thingsboard-demo_tb-network: 将Gateway容器连接到ThingsBoard核心服务所在的Docker网络。网络名称通常是“项目目录名_网络名”你可以用docker network ls查看确认。thingsboard/tb-gateway: 使用的官方Gateway镜像。运行后查看Gateway日志确认其成功连接到了ThingsBoard和配置的MQTT Brokerdocker logs -f tb-gateway你应该看到类似 “Gateway connected to ThingsBoard!” 和 “MQTT Broker Connector connected to broker...” 的成功信息。4.4 测试数据流发布MQTT消息并验证现在整个链路已经打通公共MQTT Broker (test.mosquitto.org) 上test/topic主题的消息。ThingsBoard Gateway 订阅并接收这些消息。Gateway 将消息转换后通过MQTT协议发送给本地的ThingsBoard核心服务 (tb-core)。ThingsBoard 将数据存储并可通过Web UI展示。我们来模拟设备发布一条消息。你可以使用任何MQTT客户端工具比如MQTTX一个图形化客户端或者用命令行工具mosquitto_pub如果你安装了Mosquitto。使用mosquitto_pub命令发布在另一个终端窗口mosquitto_pub -h test.mosquitto.org -t test/topic -m {sensorId:OfficeSensor01,model:DHT22,temp:23.5,hum:65.2}发布后观察Gateway容器的日志应该能看到它收到了消息并成功转发。然后登录ThingsBoard Web UI (http://localhost:8080)进入“设备”页面。你应该能看到一个名为 “OfficeSensor01” 的设备被自动创建了。点击该设备在“最新遥测”标签页下应该能看到temperature和humidity两个键及其值。在“属性”标签页能看到model属性。至此从设备模拟- Gateway - ThingsBoard的完整数据链路验证成功5. 实战排坑与进阶配置指南部署过程很少一帆风顺下面是我在多次部署中总结的常见问题和进阶调整点。5.1 常见启动失败问题排查端口冲突错误信息包含Bind for 0.0.0.0:8080 failed: port is already allocated。原因你本机的8080、1883或5683端口已被其他程序占用如本地开发的其他Web服务、Mosquitto Broker等。解决方法一修改docker-compose.yml中thingsboard服务的ports映射例如将- 8080:9090改为- 18080:9090然后通过http://localhost:18080访问。方法二找出并关闭占用端口的进程。在PowerShell中使用netstat -ano | findstr :8080查找PID然后在任务管理器中结束对应进程。数据库连接失败ThingsBoard日志持续报错Connection to localhost:5432 refused或FATAL: password authentication failed for user postgres。原因ThingsBoard容器启动时PostgreSQL容器还未完全准备好健康检查未通过或者环境变量中的密码与PostgreSQL容器设置的不一致。解决确保使用了depends_on的condition: service_healthy配置。检查docker-compose.yml中postgres服务的POSTGRES_PASSWORD和thingsboard服务的SPRING_DATASOURCE_PASSWORD是否完全一致包括大小写和特殊字符。可以手动进入PostgreSQL容器检查docker exec -it tb-postgres psql -U postgres -d thingsboard。Gateway无法连接ThingsBoardGateway日志报错Failed to connect to ThingsBoard!。原因tb_gateway.yaml中的address配置错误。在Docker Compose部署中必须使用容器名tb-core而不是localhost或127.0.0.1因为localhost在Gateway容器内指向它自己。Access Token无效或对应的设备在ThingsBoard中不存在。Gateway容器没有连接到正确的Docker网络。解决确认address: tb-core。在ThingsBoard Web UI中确认设备及其Access Token。使用docker network inspect thingsboard-demo_tb-network查看网络详情确认tb-core和tb-gateway两个容器都在该网络中。磁盘空间不足运行一段时间后日志或数据占满磁盘。原因Docker容器日志或卷映射的数据文件不断增长。解决清理Docker日志docker system prune -f。配置Docker日志轮转在Docker Desktop设置中配置日志大小限制。定期清理postgres-data,redis-data等卷目录下的旧数据需谨慎避免删除重要数据。5.2 配置持久化与数据备份我们通过volumes映射已经实现了数据持久化。所有重要数据都在宿主机对应的文件夹里postgres-data,redis-data,thingsboard-data等。定期备份这些文件夹即可。如果需要迁移到另一台机器在新机器上准备好相同的目录结构和docker-compose.yml文件。将旧机器上的数据文件夹整个postgres-data等复制到新机器的对应位置。在新机器上执行docker-compose up -d。Docker会使用已有的数据启动服务。5.3 启用HTTPS访问可选对于需要安全访问的测试环境可以配置Nginx反向代理并添加SSL证书。这超出了本文核心范围但思路是创建一个Nginx容器配置SSL将443端口请求代理到ThingsBoard容器的9090端口并修改docker-compose.yml将ThingsBoard的端口映射移除或只映射到内部网络由Nginx对外暴露。5.4 Gateway连接其他协议设备本文以MQTT连接器为例。ThingsBoard Gateway的强大之处在于其丰富的连接器库。要连接Modbus设备你需要在tb_gateway.yaml的connectors部分添加一个modbus类型的连接器并指向一个modbus.json配置文件。创建modbus.json详细配置设备地址IP/串口、从站ID、寄存器地址、轮询间隔、数据转换规则等。重启Gateway容器。配置文件的修改在宿主机进行映射到容器内通常支持热加载但重启最稳妥。其他如OPC UA、CAN、BMS等连接器的配置方式类似都需要编写对应的JSON配置文件。官方文档提供了每个连接器的配置模板和参数说明。6. 日常运维与开发调试技巧环境搭起来了怎么用好它才是关键。6.1 常用的Docker命令备忘查看所有容器状态docker-compose ps或docker ps -a查看特定容器日志docker-compose logs -f thingsboard(跟踪) 或docker logs tb-gateway(最后若干行)进入容器内部调试用docker exec -it tb-core /bin/bash(ThingsBoard容器) 或docker exec -it tb-postgres psql -U postgres(直接进入PostgreSQL命令行)停止所有服务docker-compose down。注意这会停止并删除由docker-compose up创建的容器、网络但不会删除卷映射的数据./postgres-data等。如果想彻底清理数据需要手动删除这些文件夹。停止并清理数据慎用docker-compose down -v。这个命令会删除定义的卷导致所有数据丢失仅用于需要完全重置环境时。重启单个服务docker-compose restart thingsboard6.2 在IDEA或VS Code中连接本地服务进行开发如果你需要基于ThingsBoard进行二次开发这个本地Docker环境就是绝佳的测试后端。ThingsBoard REST API所有API端点位于http://localhost:8080/api/...。你可以使用Postman等工具直接测试。登录后在“账户设置” - “API令牌”中创建令牌用于API认证。MQTT客户端调试你可以编写一个本地的MQTT客户端程序Python的paho-mqtt库、Node.js的mqtt库等直接发布消息到localhost:1883主题和Payload格式遵循ThingsBoard的MQTT API这样就可以模拟设备上报数据无需经过Gateway。规则链调试在Web UI中创建复杂的规则链时可以在关键节点如“script filter”、“script switch”上启用“Debug mode”然后查看“规则引擎事件”来跟踪消息的流动和处理结果这对于调试业务逻辑至关重要。6.3 性能监控与资源限制在Windows上跑多个容器对资源是考验。可以通过Docker Desktop的仪表盘直观查看CPU、内存、磁盘和网络使用情况。如果发现资源紧张可以在docker-compose.yml中为服务添加资源限制thingsboard: # ... 其他配置 deploy: resources: limits: cpus: 1.0 memory: 2G reservations: cpus: 0.5 memory: 1G调整ThingsBoard的JVM参数可以通过环境变量JAVA_OPTS或TB_SERVER_OPTS传递给ThingsBoard容器例如-Xms1g -Xmx2g来设置堆内存。经过以上步骤你应该已经在Windows上获得了一个功能完整、数据持久化、便于调试的ThingsBoard开发测试环境。这个环境几乎复刻了Linux服务器的部署体验但所有操作都在你熟悉的Windows桌面完成。无论是学习ThingsBoard功能、测试设备接入逻辑还是进行规则链开发它都是一个高效且可靠的沙箱。