📚 课程目录第4章边缘版安装部署

4. 边缘版安装部署

ThingsBoard边缘版（Edge Edition）的部署质量直接决定后续设备接入、数据同步与规则链执行的稳定性。与单机版不同，边缘版需要同时管理本地数据库、消息队列、HTTP/CoAP/MQTT传输服务以及与云端TB CE/PE实例的gRPC同步通道。本章围绕Docker Compose这一主流编排工具，从部署架构、配置清单、数据库初始化到首次启动验证，形成一条可复现、可排障的完整路径。以下先给出边缘版部署的整体工程链路，再逐层展开操作细节。

上图展示了边缘版部署的四个核心阶段与容器组件拓扑。实际生产环境中，边缘版通常部署在靠近设备侧的网关或工业PC上，资源占用需控制在2核CPU/4GB内存以上。下面从核心原理开始，逐步讲解每个环节的具体操作。

4.1 核心原理：Docker Compose如何组织边缘版服务

ThingsBoard边缘版不是单一二进制文件，而是由多个相互协作的模块组成：传输层（HTTP/MQTT/CoAP）、核心服务（规则引擎、实体管理）、数据库（PostgreSQL）、缓存/消息队列（Redis）、UI界面（tb-edge-ui）以及云端同步模块（gRPC客户端）。Docker Compose通过声明式YAML文件，将这些服务定义为多个容器，并统一管理网络、卷、环境变量和依赖顺序。

边缘版与云端版的关键差异在于：边缘版必须配置云终端连接参数（cloud.endpoint、cloud.routing.key等），否则无法与ThingsBoard CE/PE实例建立安全通道。此外，边缘版默认使用本地PostgreSQL存储设备元数据和遥测数据，而云端版可能使用Cassandra或混合数据库。理解这一点，有助于在配置文件中准确区分哪些参数控制本地行为，哪些参数控制云端同步。

部署架构要点：边缘版容器组中，tb-edge是主进程容器，负责加载规则链、处理设备消息；postgres容器存储持久化数据；redis容器用于缓存和临时队列；tb-edge-ui容器提供Web管理界面。四个容器通过内部网络（默认bridge）通信，对外仅暴露必要端口（如8080、1883、5683）。

4.2 操作流程：编写docker-compose.yml与配置文件详解

首先创建项目目录并准备两个核心文件：docker-compose.yml和tb-edge.env。以下是一个经过生产验证的最小化配置模板（基于ThingsBoard Edge 3.5+版本）：

version: '3.0'
services:
  tb-edge:
    image: thingsboard/tb-edge:3.5.1
    restart: always
    ports:
      - "8080:8080"      # HTTP/UI
      - "1883:1883"      # MQTT
      - "5683:5683/udp"  # CoAP
    env_file:
      - tb-edge.env
    environment:
      - TB_QUEUE_TYPE=in-memory   # 轻量部署使用内存队列
    volumes:
      - tb-edge-data:/data
      - tb-edge-logs:/var/log/thingsboard
    depends_on:
      - postgres
      - redis
    networks:
      - tb-edge-net

  postgres:
    image: postgres:15
    restart: always
    environment:
      - POSTGRES_DB=thingsboard
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - tb-edge-net

  redis:
    image: redis:7-alpine
    restart: always
    networks:
      - tb-edge-net

volumes:
  tb-edge-data:
  tb-edge-logs:
  postgres-data:

networks:
  tb-edge-net:
    driver: bridge

tb-edge.env文件包含关键配置项，需根据实际云端实例信息修改：

# 云端连接配置
CLOUD_ENDPOINT=your-cloud-instance.com
CLOUD_PORT=7070
CLOUD_ROUTING_KEY=your_routing_key
CLOUD_ROUTING_SECRET=your_routing_secret

# 数据库配置
SPRING_DATASOURCE_URL=jdbc:postgresql://postgres:5432/thingsboard
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=postgres

# 基础配置
TB_EDGE_INSTALLATION_METHOD=docker
TB_EDGE_LICENSE_SECRET=your_license_secret

配置文件中最重要的三组参数：云端连接参数（CLOUD_*）、数据库连接参数（SPRING_DATASOURCE_*）、队列类型（TB_QUEUE_TYPE）。生产环境建议将TB_QUEUE_TYPE改为kafka或rabbitmq，但需要额外部署对应容器，本章为快速部署采用in-memory模式。

配置项	作用域	典型值	说明
CLOUD_ENDPOINT	云端同步	tb.mycompany.com	云端ThingsBoard实例地址
CLOUD_ROUTING_KEY	云端同步	UUID字符串	从云端实例边缘管理页面获取
SPRING_DATASOURCE_URL	本地存储	jdbc:postgresql://postgres:5432/thingsboard	容器间使用服务名postgres
TB_QUEUE_TYPE	消息队列	in-memory / kafka	生产环境建议kafka
TB_EDGE_LICENSE_SECRET	许可	Base64字符串	商业版需要，社区版可留空

4.3 数据库初始化：自动建表与手动干预

ThingsBoard边缘版在首次启动时会自动执行数据库初始化脚本，创建所需的表结构、索引和系统级数据（如默认管理员账号、系统规则链）。这一过程由install.sh逻辑触发，在容器启动时通过docker-compose up自动完成。但需要注意：数据库初始化是幂等的，重复执行不会破坏已有数据，但会尝试应用增量迁移脚本。

如果遇到初始化失败（常见于PostgreSQL版本不匹配或权限不足），可手动进入容器执行初始化命令：

docker-compose exec tb-edge bash
# 在容器内执行
cd /app && java -jar tb-edge.jar --install

初始化完成后，PostgreSQL中会生成约200+张表，核心表包括device、asset、entity_view、rule_chain、event等。验证数据库是否就绪，可通过以下命令检查表数量：

docker-compose exec postgres psql -U postgres -d thingsboard -c "\dt" | wc -l

风险提示：不要在生产环境使用默认密码postgres。数据库初始化完成后，应立即修改PostgreSQL密码，并同步更新tb-edge.env中的SPRING_DATASOURCE_PASSWORD，然后重启tb-edge容器。

4.4 首次启动与验证：从日志到功能测试

执行docker-compose up -d后，系统会拉取镜像并启动容器。首次启动通常需要2-5分钟（取决于网络和机器性能）。验证过程分为三个层次：容器状态验证、应用日志验证、功能接口验证。

第一步：容器状态检查

docker-compose ps
# 期望输出：所有容器状态为 "Up" 或 "healthy"

第二步：日志验证，重点查看tb-edge容器日志中是否出现以下关键行：

docker-compose logs -f tb-edge | grep -E "Started|ERROR|Exception"
# 成功标志：Started ThingsBoardEdgeApplication in 45.2 seconds

第三步：功能接口验证，通过REST API检查系统健康状态：

curl -s http://localhost:8080/api/health | jq .
# 期望返回：{"status":"UP","components":{"db":{"status":"UP"},"redis":{"status":"UP"}}}

同时验证Web UI是否可访问：浏览器打开http://localhost:8080，使用默认管理员账号sysadmin@thingsboard.org / sysadmin登录。登录后应能看到边缘版仪表盘，且左侧菜单出现“边缘管理”选项。

4.5 案例拆解：从零部署到设备接入的完整闭环

某智慧工厂项目需要在车间部署边缘节点，管理50+台PLC设备，并与云端ThingsBoard CE实例同步。初始环境为Ubuntu 22.04服务器（4核CPU/8GB内存），已安装Docker 24.0和docker-compose 2.20。

实施过程：

在云端ThingsBoard界面创建边缘实例，获取routing key和routing secret。
编写docker-compose.yml和tb-edge.env，将云端参数填入。
执行docker-compose up -d，等待约3分钟。
检查日志发现ERROR: Failed to connect to cloud endpoint，排查发现CLOUD_PORT配置错误（应为7070而非默认的8080）。
修正配置后重启，日志显示Cloud connection established。
在边缘版UI中创建设备，使用MQTT模拟器发送测试数据，确认数据写入本地PostgreSQL。
在云端实例中查看边缘同步状态，确认设备元数据和遥测数据已同步。

结果对比：部署耗时从手工安装的2小时缩短至20分钟；数据同步延迟小于1秒；边缘节点在断网情况下仍可本地存储数据，恢复后自动补传。

经验复盘：边缘版部署中最常见的三个坑：① 云端端口配置错误（默认7070）；② 数据库密码未同步修改导致重启失败；③ 内存不足导致容器OOM（建议至少4GB可用内存）。建议在部署前使用docker-compose config验证配置语法，并预留足够资源。

4.6 常见误区与总结复盘

通过多个项目的部署实践，总结以下高频误区和应对策略：

误区一：忽略云端同步参数。部分用户仅配置本地数据库，导致边缘版无法与云端通信。务必检查CLOUD_ENDPOINT、CLOUD_ROUTING_KEY等参数。
误区二：使用默认数据库密码。生产环境必须修改，否则存在严重安全风险。
误区三：端口冲突未排查。边缘版默认占用8080、1883、5683端口，部署前需确认这些端口未被占用。
误区四：忽略日志中的WARN信息。例如Unable to connect to Redis，虽然不影响启动，但会导致缓存功能异常。

总结：Docker Compose部署边缘版的核心在于理解服务间依赖关系、正确配置云端连接参数、验证数据库初始化结果。建议将docker-compose.yml和tb-edge.env纳入版本管理，便于回滚和团队协作。对于生产环境，还应配置日志轮转、资源限制（deploy.resources.limits）和健康检查探针，确保长期稳定运行。