- 前置条件
- 步骤 1. 克隆 ThingsBoard PE K8S 脚本仓库
- 步骤 2. 配置并创建 EKS 集群
- 步骤 3. 创建 AWS 负载均衡控制器
- 步骤 4. 配置数据库
- 步骤 5. 获取并配置许可证密钥
- 步骤 6. 安装
- 步骤 7. 启动
- 步骤 8. 配置负载均衡器
- 步骤 9. 配置 Trendz（可选）
- 步骤 10. 验证设置
- 升级
- 集群删除
- 后续步骤
本指南将帮助您在 AWS EKS 中以单体模式设置 ThingsBoard。
前置条件
安装和配置工具
要在 EKS 集群上部署 ThingsBoard，您需要安装 kubectl、
eksctl 和
awscli 工具。
安装后需要配置 Access Key、Secret Key 和默认区域。 请按照此指南获取 Access Key 和 Secret Key。 默认区域应为计划部署集群的区域 ID。
1
aws configure
从 Docker Hub 拉取 ThingsBoard PE 镜像
运行以下命令验证您能否从 Docker Hub 拉取镜像。
1
2
docker pull thingsboard/tb-pe-node:4.3.0.1PE
docker pull thingsboard/tb-pe-web-report:4.3.0.1PE
步骤 1. 克隆 ThingsBoard PE K8S 脚本仓库
1
2
git clone -b release-4.3.0.1 https://github.com/thingsboard/thingsboard-pe-k8s.git --depth 1
cd thingsboard-pe-k8s/aws/monolith
步骤 2. 配置并创建 EKS 集群
在 cluster.yml 文件中可找到推荐的集群配置。
以下字段可根据需要修改：
region- 集群所在的 AWS 区域（默认us-east-1）availabilityZones- 该区域可用区的具体 ID（默认[us-east-1a,us-east-1b,us-east-1c]）instanceType- 运行 TB 节点的实例类型（默认m5.xlarge）
注意：若不修改 instanceType 和 desiredCapacity，EKS 将部署 1 node of type m5.xlarge。
以下命令将为 ThingsBoard 集群创建新的 VPC。本指南假设您将创建新 VPC。 使用现有 VPC 和子网也可以。 有关为 eksctl 配置 VPC 的更多信息请参阅 此处。
创建 AWS 集群的命令：
1
eksctl create cluster -f cluster.yml
步骤 3. 创建 AWS 负载均衡控制器
集群就绪后，您必须创建 AWS 负载均衡器控制器。 您可以按照此指南操作。 集群预置脚本将创建多个负载均衡器：
- “tb-http-loadbalancer” - 负责 Web UI、REST API 和 HTTP 传输的 AWS ALB；
- “tb-mqtt-loadbalancer” - 负责 MQTT 传输的 AWS NLB；
- “tb-coap-loadbalancer” - 负责 CoAP 传输的 AWS NLB；
- “tb-edge-loadbalancer” - 负责 Edge 实例连接的 AWS NLB；
AWS 负载均衡器控制器的预置是非常重要的一步，这些负载均衡器需要它才能正常工作。
步骤 4. 配置数据库
步骤 4.1 Amazon PostgreSQL 数据库配置
需在 Amazon RDS 上配置 PostgreSQL。ThingsBoard 将使用其作为主数据库存储设备、仪表盘、规则链和遥测数据。 可参考此指南，并注意以下要求：
- 妥善保管 postgresql 密码，本指南后续将用 YOUR_RDS_PASSWORD 指代；
- PostgreSQL 版本需为最新 16.x；
- 确保 PostgreSQL RDS 实例可从 ThingsBoard 集群访问； 最简单的做法是在同一 VPC 部署 RDS 实例，并采用 ‘eksctl-thingsboard-cluster-ClusterSharedNodeSecurityGroup-*’ 安全组。 本指南默认采用同一 VPC；
- 初始数据库名需使用 “thingsboard”。若不指定数据库名，Amazon RDS 不会创建数据库；
建议：
- 使用「Production」模板以获得高可用，默认开启多项实用配置；
- 使用「Provisioned IOPS」提升性能；
- 为 RDS 实例创建自定义参数组，便于修改 DB 参数；
- 将 RDS 实例部署到私有子网，降低意外暴露到互联网的风险。
数据库切换为「Available」后，进入「Connectivity and Security」，复制 endpoint 值。
编辑 tb-node-db-configmap.yml，将 YOUR_RDS_ENDPOINT_URL 和 YOUR_RDS_PASSWORD 替换为实际值。
步骤 4.2 Cassandra（可选）
使用 Cassandra 为可选步骤。 若计划每秒插入超过 5K 数据点或需优化存储空间，建议使用 Cassandra。
配置额外节点组
配置用于承载 Cassandra 实例的额外节点组。 可修改机型，建议至少 4 vCPU 和 16GB 内存。
将创建 3 个独立节点池，每个可用区 1 个节点。 因使用 EBS 磁盘，需避免 k8s 在对应磁盘不可用的可用区启动 pod。 这些可用区使用相同节点标签，我们将用该标签指定 StatefulSet 的部署目标。
在不同可用区部署 3 个 m5.xlarge 节点。可根据您的区域调整可用区：
1
eksctl create nodegroup --config-file=<path> --include='cassandra-*'
部署 Cassandra StatefulSet
创建 ThingsBoard 命名空间：
1
2
kubectl apply -f tb-namespace.yml
kubectl config set-context $(kubectl config current-context) --namespace=thingsboard
将 Cassandra 部署到新节点组：
1
kubectl apply -f receipts/cassandra.yml
Cassandra 集群启动可能需要几分钟。您可以使用以下命令监控进程：
1
kubectl get pods
更新数据库设置
编辑 ThingsBoard 数据库设置文件并添加 Cassandra 设置. Don’t forget to replace YOUR_AWS_REGION with the name of your AWS region.
1
2
3
echo " DATABASE_TS_TYPE: cassandra" >> tb-node-db-configmap.yml
echo " CASSANDRA_URL: cassandra:9042" >> tb-node-db-configmap.yml
echo " CASSANDRA_LOCAL_DATACENTER: YOUR_AWS_REGION" >> tb-node-db-configmap.yml
确认设置已更新：
1
cat tb-node-db-configmap.yml | grep DATABASE_TS_TYPE
预期输出：
1
DATABASE_TS_TYPE: cassandra
创建 keyspace
使用以下命令创建 thingsboard keyspace：
1
2
3
4
5
6
kubectl exec -it cassandra-0 -- bash -c "cqlsh -e \
\"CREATE KEYSPACE IF NOT EXISTS thingsboard \
WITH replication = { \
'class' : 'NetworkTopologyStrategy', \
'us-east' : '3' \
};\""
步骤 5. 获取并配置许可证密钥
我们假设您已选择订阅计划或决定购买永久许可证。 若尚未选择，请前往定价页面为您的场景选择最佳许可证并获取许可证。 更多详情请参阅 如何获取按需付费订阅 或 如何获取永久许可证。
使用您的许可证密钥创建 docker secret：
1
2
export TB_LICENSE_KEY=PUT_YOUR_LICENSE_KEY_HERE
kubectl create -n thingsboard secret generic tb-license --from-literal=license-key=$TB_LICENSE_KEY
请勿忘记将 PUT_YOUR_LICENSE_KEY_HERE 替换为您的许可证密钥值。
步骤 6. 安装
执行以下命令运行数据库的初始设置。该命令将启动短生命周期的 ThingsBoard Pod 以配置必要的数据库表、索引等。
1
./k8s-install-tb.sh --loadDemo
其中：
--loadDemo- 可选参数。是否加载额外的演示数据。
此命令完成后，您应在控制台看到以下输出：
1
Installation finished successfully!
否则，请检查是否在 tb-node-db-configmap.yml 中正确设置了 PostgreSQL URL 和 PostgreSQL 密码。
步骤 7. 启动
执行以下命令部署资源：
1
./k8s-deploy-resources.sh
几分钟后可执行 kubectl get pods。若一切正常，您应能看到 tb-node-0 pod 处于 READY 状态。
步骤 8. 配置负载均衡器
8.1 配置 HTTP(S) 负载均衡器
配置 HTTP(S) 负载均衡器以访问 ThingsBoard 实例的 Web 界面。主要有 2 种配置选项：
- http - 不支持 HTTPS 的负载均衡器。适用于开发环境。 唯一优势是配置简单、成本最低。适合开发服务器，但不适合生产环境。
- https - 支持 HTTPS 的负载均衡器。适用于生产环境。 作为 SSL 终止点。 可轻松配置以签发和维护有效的 SSL 证书。自动将所有非安全（HTTP）流量重定向到安全（HTTPS）端口。
请参阅下方链接/说明了解如何配置每种建议选项。
HTTP 负载均衡器
执行以下命令部署纯 HTTP 负载均衡器：
1
kubectl apply -f receipts/http-load-balancer.yml
负载均衡器预置可能需要一些时间。您可以使用以下命令定期检查负载均衡器状态：
1
kubectl get ingress
预置完成后，您应看到类似输出：
1
2
NAME CLASS HOSTS ADDRESS PORTS AGE
tb-http-loadbalancer <none> * 34.111.24.134 80 7m25s
现在，您可以使用该地址（命令输出中替代 34.111.24.134 的地址）访问 HTTP Web UI（端口 80）并通过 HTTP API 连接设备 使用以下默认凭据：
- 系统管理员：sysadmin@thingsboard.org / sysadmin
- 租户管理员：tenant@thingsboard.org / tenant
- 客户用户：customer@thingsboard.org / customer
HTTPS 负载均衡器
使用 AWS Certificate Manager 创建或导入 SSL 证书。记下证书 ARN。
编辑负载均衡器配置，将 YOUR_HTTPS_CERTIFICATE_ARN 替换为您的证书 ARN：
1
nano receipts/https-load-balancer.yml
执行以下命令部署纯 HTTPS 负载均衡器：
1
kubectl apply -f receipts/https-load-balancer.yml
8.2. 配置 MQTT 负载均衡器（可选）
若计划使用 MQTT 协议连接设备，请配置 MQTT 负载均衡器。
使用以下命令创建 TCP 负载均衡器：
1
kubectl apply -f receipts/mqtt-load-balancer.yml
该负载均衡器将转发端口 1883 和 8883 的所有 TCP 流量。
单向 TLS
配置 MQTTS 的最简单方式是让 MQTT 负载均衡器（AWS NLB）作为 TLS 终止点。 这样我们建立单向 TLS 连接：设备与负载均衡器之间的流量被加密，负载均衡器与 MQTT 传输服务之间的流量不加密。 由于 ALB/NLB 在您的 VPC 内运行，不应存在安全问题。 此方案的主要缺点是无法使用「X.509 证书」类 MQTT 客户端凭据，因为客户端证书信息不会从负载均衡器传递到 ThingsBoard MQTT 传输服务。
要启用 单向 TLS：
使用 AWS Certificate Manager 创建或导入 SSL 证书。记下证书 ARN。
编辑负载均衡器配置，将 YOUR_MQTTS_CERTIFICATE_ARN 替换为您的证书 ARN：
1
nano receipts/mqtts-load-balancer.yml
执行以下命令部署纯 HTTPS 负载均衡器：
1
kubectl apply -f receipts/mqtts-load-balancer.yml
双向 TLS
启用 MQTTS 的更复杂方式是获取有效（已签名）的 TLS 证书并在 MQTT 传输中配置。此方案的主要优势是可与「X.509 证书」类 MQTT 客户端凭据配合使用。
要启用 双向 TLS：
按照 本指南 创建包含 SSL 证书的 .pem 文件。 将文件以 server.pem 保存在工作目录中。
需要创建包含 PEM 文件的 config-map，可执行：
1
2
3
4
kubectl create configmap tb-mqtts-config \
--from-file=server.pem=YOUR_PEM_FILENAME \
--from-file=mqttserver_key.pem=YOUR_PEM_KEY_FILENAME \
-o yaml --dry-run=client | kubectl apply -f -
- YOUR_PEM_FILENAME 为 服务器证书文件 名称。
- YOUR_PEM_KEY_FILENAME 为 服务器证书私钥文件 名称。
然后，取消 ‘tb-node.yml’ 文件中所有标有「Uncomment the following lines to enable two-way MQTTS」的段落注释。
执行以下命令使更改生效：
1
kubectl apply -f tb-node.yml
最后，部署「透明」负载均衡器：
1
kubectl apply -f receipts/mqtt-load-balancer.yml
8.3. 配置 UDP 负载均衡器（可选）
若计划使用 CoAP 或 LwM2M 协议连接设备，请配置 UDP 负载均衡器。
使用以下命令创建 UDP 负载均衡器：
1
kubectl apply -f receipts/udp-load-balancer.yml
该负载均衡器将转发以下端口的全部 UDP 流量：
- 5683 - CoAP 服务器非安全端口
- 5684 - CoAP 服务器安全 DTLS 端口
- 5685 - LwM2M 服务器非安全端口
- 5686 - LwM2M 服务器安全 DTLS 端口
- 5687 - LwM2M 引导服务器 DTLS 端口
- 5688 - LwM2M 引导服务器安全 DTLS 端口
CoAP over DTLS
此类负载均衡器需您自行准备并维护有效 SSL 证书。 请按通用 CoAP over DTLS 指南， 在 tb-node.yml 文件中配置所需环境变量。
LwM2M over DTLS
此类负载均衡器需您自行准备并维护有效 SSL 证书。 请按通用 LwM2M over DTLS 指南， 在 tb-node.yml 文件中配置所需环境变量。
8.4. 配置 Edge 负载均衡器（可选）
若计划将 Edge 实例连接到 ThingsBoard 服务器，需配置 Edge 负载均衡器。
要创建 TCP Edge 负载均衡器，使用以下命令应用提供的 YAML 文件：
1
kubectl apply -f receipts/edge-load-balancer.yml
负载均衡器将转发端口 7070 上的所有 TCP 流量。
Edge 负载均衡器配置完成后，可将 Edge 实例连接到 ThingsBoard 服务器。
连接 Edge 实例前，需获取 Edge 负载均衡器的外部 IP 地址。执行以下命令获取该 IP：
1
kubectl get services | grep "EXTERNAL-IP\|tb-edge-loadbalancer"
应看到类似以下输出：
1
2
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
tb-edge-loadbalancer LoadBalancer 10.44.5.255 104.154.29.225 7070:30783/TCP 85m
记下外部 IP 地址，并在 Edge 连接参数中将 CLOUD_RPC_HOST 设为该地址。
步骤 9. 配置 Trendz（可选）
9.1. 从 Docker Hub 拉取 Trendz 镜像
运行以下命令以验证可从 Docker Hub 拉取镜像：
1
2
docker pull thingsboard/trendz:1.15.0.4
docker pull thingsboard/trendz-python-executor:1.15.0.4
9.2. 在现有 RDS 实例中创建 Trendz 数据库
编辑 “trendz/trendz-secret.yml” ，将 YOUR_RDS_ENDPOINT_URL 和 YOUR_RDS_PASSWORD 替换后执行 Kubernetes Job：
1
2
kubectl apply -f ./trendz/trendz-secret.yml
kubectl apply -f ./trendz/trendz-create-db.yml
执行以下命令可查看日志：
1
kubectl logs job/trendz-create-db -n thingsboard
9.3. 启动 Trendz
执行以下命令以运行数据库初始设置。该命令将启动短期存在的 ThingsBoard pod 以创建必要的 DB 表、索引等：
1
./k8s-deploy-trendz.sh
命令完成后，控制台应显示：
1
Trendz installed successfully!
否则，请检查 trendz-secret.yml 中的 PostgreSQL URL 和 PostgreSQL 密码是否配置正确。
步骤 10. 验证设置
验证 Web UI 访问
现在您可以在浏览器中使用负载均衡器的 DNS 名称打开 ThingsBoard Web 界面。
您可以使用以下命令查看 HTTP 负载均衡器的 DNS 名称（ADDRESS 列）：
1
kubectl get ingress
您应该看到类似的输出：
使用以下默认凭据：
- 系统管理员：sysadmin@thingsboard.org / sysadmin
如果使用 --loadDemo 标志安装了带演示数据的数据库，您还可以使用以下凭据：
- 租户管理员：tenant@thingsboard.org / tenant
- 客户用户：customer@thingsboard.org / customer
验证 MQTT/CoAP 访问
要通过 MQTT 或 COAP 连接集群，需要获取对应的服务，可使用以下命令：
1
kubectl get service
您应该看到类似的输出：
有两个负载均衡器：
- tb-mqtt-loadbalancer-external - 用于 MQTT 协议
- tb-coap-loadbalancer-external - 用于 COAP 协议
使用负载均衡器的 EXTERNAL-IP 字段连接集群。
故障排查
如遇问题，可以检查服务日志以查找错误。 例如，要查看 ThingsBoard 节点日志，请执行以下命令：
1
kubectl logs -f tb-node-0
或使用 kubectl get pods 查看 Pod 状态。
或使用 kubectl get services 查看所有服务状态。
或使用 kubectl get deployments 查看所有部署状态。
详见 kubectl 速查表 命令参考。
升级
升级到新版 ThingsBoard
将本地修改与 步骤 1 所用仓库的最新发布分支合并。
如需升级数据库，请执行以下命令：
1
./k8s-upgrade-tb.sh --fromVersion=[FROM_VERSION]
其中：
FROM_VERSION- 从哪个版本开始升级。有效fromVersion值请参见 升级说明。注意，需按顺序逐版本升级（例如 3.6.1 -> 3.6.2 -> 3.6.3）。
注意：升级数据库时，可选择停止 tb-node pods。这将导致停机，但能确保更新后数据库状态一致。 大多数更新无需停止 tb-nodes。
完成后，再次执行资源部署。这将触发 thingsboard 组件的滚动重启并更新到最新版本。
1
./k8s-deploy-resources.sh
升级到新版 Trendz（可选）
若要升级，请从 master 分支拉取最新更改：
1
git pull origin master
然后执行以下命令：
1
./k8s-upgrade-trendz.sh
注意，可从任意版本直接升级 Trendz 至最新版本（例如 1.12.0 -> 1.15.0 等）。
集群删除
执行以下命令删除所有 ThingsBoard Pod：
1
./k8s-delete-resources.sh
执行以下命令删除所有 ThingsBoard Pod 和 ConfigMap：
1
./k8s-delete-all.sh
执行以下命令删除 EKS 集群（您需要修改集群名称和可用区）：
1
eksctl delete cluster -r us-east-1 -n thingsboard -w