Ubuntu 24.04 上用 Kubernetes（Minikube）部署 ThingsBoard CE

本文给出一套可直接复制执行的 ThingsBoard Community Edition Kubernetes 部署流程，环境固定为：

项	取值
操作系统	Ubuntu 24.04 LTS（x86_64）
编排	Minikube + kubectl（官方 CE 集群入门方式）
脚本仓库 / 分支	thingsboard/thingsboard-ce-k8s · release-4.3.1.8
镜像版本	thingsboard/*:4.3.1.8（与脚本一致）
数据库（默认）	PostgreSQL only（DATABASE=postgres）

官方依据：Cluster setup using Minikube（CE）。

说明： 专栏原稿 9、ThingsBoard使用k8s部署.docx 当前为空文件，本文以官网 CE Minikube 流程 + 仓库脚本实核为准，并补齐 Ubuntu 24.04 从零安装步骤。
单节点 Docker Compose 见：Ubuntu系统部署 ThingsBoard 4.3.x。msa 自建镜像 / Harbor 见前文，生产可把脚本里的镜像地址改成你的仓库。

---

0. 你将得到什么

部署成功后，集群命名空间 thingsboard 中会运行微服务架构组件（与官方脚本一致），主要包括：

• 依赖： Zookeeper、Kafka、Valkey（缓存）、PostgreSQL
• 业务： tb-node、tb-web-ui、tb-js-executor、HTTP / MQTT / CoAP Transport 等
• 入口： Ingress（HTTP Web / API）；MQTT 等为 Service（部分为 LoadBalancer）

浏览器访问：

http://<minikube-ip>/

---

1. 机器要求（请先满足）

项目	建议
CPU	≥ 4 核（Minikube 建议分配 4）
内存	宿主机 ≥ 16 GB；Minikube 至少分配 8 GB（内存紧可用 8 GB 宿主机 + 6 GB 给 Minikube，但易 OOM）
磁盘	≥ 40 GB 可用
网络	能拉取 Docker Hub（thingsboard/*）及 GitHub；国内常需镜像加速 / 代理
权限	可 sudo 的普通用户

混合库（PostgreSQL + Cassandra）更吃内存，入门请用默认 postgres。

---

2. 安装 Docker（Ubuntu 24.04）

sudo apt update
sudo apt install -y ca-certificates curl gnupg git
sudo apt install -y docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"

注销并重新登录（或重启），使 docker 组生效，然后验证：

docker version
docker run --rm hello-world

也可用 Docker 官方 docker-ce 源；Minikube --driver=docker 需要本机 Docker 可用。

（可选）Docker Hub 较慢时配置镜像加速，见 Ubuntu Docker 部署文 中的 daemon.json 示例，改完后：

sudo systemctl restart docker

---

3. 安装 kubectl

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl
kubectl version --client

---

4. 安装并启动 Minikube

4.1 安装 Minikube

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube
minikube version

4.2 启动集群（资源请按机器调整）

minikube start --driver=docker --cpus=4 --memory=8192 --disk-size=40g

验证：

kubectl cluster-info
kubectl get nodes

节点应为 Ready。

4.3 启用 Ingress（官方要求）

Minikube 默认关闭 Ingress插件，必须开启：

minikube addons enable ingress
kubectl -n ingress-nginx get pods

等到 Ingress Controller Pod 为 Running / READY 再继续（可多等一两分钟）。

---

5. 克隆官方 CE Kubernetes 脚本（钉死 4.3.1.8）

cd ~
git clone -b release-4.3.1.8 https://github.com/thingsboard/thingsboard-ce-k8s.git --depth 1
cd ~/thingsboard-ce-k8s/minikube
chmod +x *.sh
ls

后续命令默认都在 ~/thingsboard-ce-k8s/minikube 目录执行。

---

6. 配置数据库类型

编辑 .env：

nano .env

默认内容（官方仓库当前即为）：

DATABASE=postgres
CASSANDRA_REPLICATION_FACTOR=1

DATABASE	含义
postgres（推荐入门）	实体 + 时序都在 PostgreSQL
hybrid	实体 PostgreSQL，时序 Cassandra（需更多内存；可调 cassandra.yml 副本与 CASSANDRA_REPLICATION_FACTOR）

本教程按 DATABASE=postgres 往下写。 保存退出。

---

7. 安装与部署（严格按官方三步）

官方文档顺序如下，请按顺序执行，每步完成后再做下一步。

7.1 初始化安装（建库表 / 可选 Demo）

cd ~/thingsboard-ce-k8s/minikube
./k8s-install-tb.sh --loadDemo

说明：

• 脚本会创建命名空间 thingsboard、应用 thirdparty.yml，并按 .env 部署 PostgreSQL（及 hybrid 时的 Cassandra），再跑安装 Job 初始化 ThingsBoard。
• --loadDemo：加载演示租户、仪表盘、设备；不要演示数据则去掉该参数：./k8s-install-tb.sh
• 首次拉镜像较慢，请保持网络畅通；失败时看下方排错。

切换到命名空间（脚本也会设置 context，可再确认）：

kubectl config set-context --current --namespace=thingsboard
kubectl get pods

此时应能看到 Zookeeper / Kafka / Valkey / Postgres 等依赖，以及安装过程相关 Pod（安装结束 tb-db-setup 会被删除）。

7.2 部署第三方依赖清单

./k8s-deploy-thirdparty.sh

该脚本对 thirdparty.yml 执行 kubectl apply（与安装脚本中的应用可重复，属幂等）。若有交互提示（部分环境 / 高可用相关），按官方说明输入 yes。

7.3 部署 ThingsBoard 业务资源

./k8s-deploy-resources.sh

会应用 ConfigMap、thingsboard.yml、tb-node.yml、routes.yml（Ingress）等。

等待所有业务 Pod Ready：

kubectl get pods -n thingsboard -w

关注例如：tb-node、tb-web-ui、tb-mqtt-transport、tb-http-transport、tb-js-executor 等均为 Running 且 READY 满足预期后，按 Ctrl+C 退出监视。

查看 Ingress：

kubectl get ingress -n thingsboard
kubectl get svc -n thingsboard

---

8. 访问 Web UI

minikube ip

浏览器打开（把 IP 换成上一步输出）：

http://<minikube-ip>/

或：

echo "http://$(minikube ip)/"

默认账号（登录后立刻改密）：

角色	邮箱	密码	需 --loadDemo
系统管理员	sysadmin@thingsboard.org	sysadmin	否
租户管理员	tenant@thingsboard.org	tenant	是
客户用户	customer@thingsboard.org	customer	是

---

9. MQTT 等端口（可选）

脚本中 MQTT Transport 等可能使用 LoadBalancer 类型 Service。在 Minikube 上常需另开终端执行：

minikube tunnel

保持该终端运行，再用：

kubectl get svc -n thingsboard

查看 EXTERNAL-IP / 端口后，用 MQTT 客户端连接。仅验证 Web 时可跳过本步。

设备上报 Topic / Token 用法与单机版相同，可参考 源码编译文 · MQTTX 或官方 MQTT Device API。

---

10. 日常运维命令

# 当前命名空间建议为 thingsboard
kubectl config set-context --current --namespace=thingsboard

kubectl get pods
kubectl get pods -l app=tb-node
kubectl logs -f deploy/tb-node
# 或
kubectl logs -f <某个-tb-node-Pod名>

kubectl get services
kubectl get deployments
kubectl get ingress

清理脚本（均在 minikube 目录）：

脚本	作用
./k8s-delete-resources.sh	删除 ThingsBoard 业务微服务
./k8s-delete-thirdparty.sh	删除第三方依赖
./k8s-delete-all.sh	删除命名空间内资源（含 PVC / 数据，慎用）

升级请严格按官方「逐版本升级」说明操作（先 k8s-delete-resources.sh → k8s-upgrade-tb.sh → k8s-deploy-resources.sh），详见官网同一页的 Upgrading 小节。

---

11. 排错速查

现象	处理
minikube start 失败	确认 Docker 已启动；内存是否够；minikube delete 后加大 --memory 再 start
Ingress 无地址 / 打不开网页	minikube addons enable ingress；等 ingress-nginx Pod Ready；用 minikube ip 访问 HTTP
k8s-install-tb.sh 卡在拉镜像	配 Docker / Minikube 镜像加速或代理；minikube ssh 内测试网络
Pod ImagePullBackOff	检查能否拉取 thingsboard/tb-node:4.3.1.8 等；分支必须与镜像版本一致（本教程 release-4.3.1.8）
tb-db-setup / install 超时	kubectl describe pod ...、kubectl logs；确认 Postgres Ready；内存不足则加大 Minikube 内存后重来（必要时 ./k8s-delete-all.sh 后重装）
只有部分 Transport	属正常裁剪；本仓库 thingsboard.yml 含 js-executor、mqtt/http/coap、web-ui 等，以实际 yaml 为准
想用自建 Harbor 镜像	改 yaml 中 image:，并配置 imagePullSecrets；构建见 msa 构建并上传 Harbor
宿主机重启后	通常需再 minikube start，再 kubectl get pods -n thingsboard 确认

完全重来（会清空该命名空间数据）：

cd ~/thingsboard-ce-k8s/minikube
./k8s-delete-all.sh
# 如需连 Minikube 一并重建：
# minikube delete && minikube start --driver=docker --cpus=4 --memory=8192 --disk-size=40g
# minikube addons enable ingress
# 然后从第 7 节重新执行三步

---

12. 命令清单（复制用）

在一台全新的 Ubuntu 24.04上，满足硬件与网络后，核心路径可概括为：

# --- 一次性：Docker / kubectl / Minikube ---
sudo apt update
sudo apt install -y ca-certificates curl gnupg git docker.io
sudo systemctl enable --now docker
sudo usermod -aG docker "$USER"
# 重新登录后再继续

curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl

curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64
sudo install minikube-linux-amd64 /usr/local/bin/minikube

minikube start --driver=docker --cpus=4 --memory=8192 --disk-size=40g
minikube addons enable ingress

# --- ThingsBoard CE 4.3.1.8 ---
cd ~
git clone -b release-4.3.1.8 https://github.com/thingsboard/thingsboard-ce-k8s.git --depth 1
cd ~/thingsboard-ce-k8s/minikube
chmod +x *.sh
# 确认 .env 中 DATABASE=postgres

./k8s-install-tb.sh --loadDemo
./k8s-deploy-thirdparty.sh
./k8s-deploy-resources.sh

kubectl get pods -n thingsboard
echo "http://$(minikube ip)/"

---

13. 小结

1. Ubuntu 24.04 上装好 Docker → kubectl → Minikube，并 minikube addons enable ingress。
2. 克隆 thingsboard-ce-k8s 的 release-4.3.1.8，进入 minikube 目录。
3. .env 用 DATABASE=postgres（入门）。
4. 依次执行：k8s-install-tb.sh → k8s-deploy-thirdparty.sh → k8s-deploy-resources.sh。
5. 浏览器打开 http://$(minikube ip)/，用默认账号登录并改密。

官方文档：Minikube 集群安装（CE） · 脚本仓库：thingsboard-ce-k8s

相关文章

• Ubuntu系统部署 ThingsBoard 4.3.x（单机 Docker Compose）
• 使用 msa 构建镜像并上传到 Harbor
• 本地打好的镜像上传到 Harbor 仓库
• ThingsBoard 项目结构介绍（release-4.3）