界面正常加载，左侧菜单栏、设备统计（9个非活动设备）、告警面板等都显示无误，这说明 ThingsBoard 不仅启动成功，而且底层 PostgreSQL 数据库连接正常，内部服务也已经完全就绪。
为了方便你以后回顾，或者帮助接手的新人快速上手，我为你整理了一份 《ThingsBoard 本地 Docker 部署与运维指导手册》。你可以直接复制到内部的 Wiki、语雀或 Markdown 文档中留存。
ThingsBoard 本地部署与运维指导手册 (Docker版)
📌 一、 环境说明与架构概览
- 部署方式 ：Docker 容器化部署（使用内置 PostgreSQL 的单机版镜像
thingsboard/tb-postgres） - 服务器 IP ：
192.168.21.16 - 默认访问端口 ：
9090(Web UI/HTTP API)、1883(MQTT)、7070(Edge RPC)、5683-5688/udp(CoAP/LwM2M) - 数据持久化目录 ：
~/.thingsboard-data(数据)、~/.thingsboard-logs(日志) - 依赖：Docker 服务必须处于运行状态
🚀 二、 安装与首次部署步骤
1. 启动 Docker 服务
bash
systemctl start docker
systemctl enable docker2. 初始化目录与权限（关键步骤）
ThingsBoard 容器内的用户（UID 799）需要写入宿主机目录，必须提前设置权限，否则会报 Permission denied 错误。
bash
mkdir -p ~/.thingsboard-data ~/.thingsboard-logs
chmod -R 777 ~/.thingsboard-data ~/.thingsboard-logs
# 或者使用 chown -R 799:799 ~/.thingsboard-data ~/.thingsboard-logs3. 运行 ThingsBoard 容器
使用以下完整的 docker run 命令启动容器（已包含解决 Git 同步报错的环境变量 ）：
使用开源的，不使用私有仓库，可以避免输入gitee的账号、密码
bash
docker run -d \
-p 9090:9090 -p 1883:1883 -p 7070:7070 \
-p 5683-5688:5683-5688/udp \
-e TB_GATEWAY_DASHBOARD_SYNC_REPOSITORY_URL=https://gitee.com/hbxxx/ateway-management-extensions-dist.git \
-v ~/.thingsboard-data:/data \
-v ~/.thingsboard-logs:/var/log/thingsboard \
--name mytb --restart always \
thingsboard/tb-postgres4. 验证启动
bash
# 查看容器状态
docker ps
# 跟踪启动日志（首次初始化约需 1-3 分钟，看到 "Started ThingsBoard" 即成功）
docker logs -f mytb⚠️ 三、 核心配置与踩坑记录
1. 解决 GitHub 拉取超时报错 (Gateways Dashboard Sync)
问题现象 ：启动日志报错 Failed to initialize repository ... github.com，导致启动缓慢或报错。
原因 ：ThingsBoard 内置了从 GitHub 同步官方仪表盘的功能，国内网络无法直接访问。
解决 ：已在启动命令中通过环境变量 TB_GATEWAY_DASHBOARD_SYNC_REPOSITORY_URL 将其替换为 Gitee 的公开镜像仓库。
注意 ：如果后续 Gitee 仓库无法访问，只需删除容器并重新执行上面的
docker run命令，替换该环境变量即可。Gitee 仓库地址：https://gitee.com/hblt_1/gateway-management-extensions-dist.git，分支为release/4.0.0。
2. 内存与资源要求
ThingsBoard 对内存有一定要求（建议服务器至少分配 2GB - 4GB 内存）。如果容器启动后莫名其妙被 Killed，请检查服务器内存：free -h。
💻 四、 日常操作指南
1. 登录系统
- 访问地址 ：
http://192.168.21.16:9090 - 系统管理员账号 ：
sysadmin@thingsboard.org/sysadmin(超级管理员，用于管理租户) - 租户管理员账号 ：
tenant@thingsboard.org/tenant(用于管理设备、仪表盘等业务) - ⚠️ 安全建议：首次登录后，请务必在【设置】中修改默认密码！
2. Docker 常用运维命令
| 操作 | 命令 |
|---|---|
| 查看容器状态 | docker ps |
| 查看实时日志 | docker logs -f mytb |
| 重启 ThingsBoard | docker restart mytb |
| 停止 ThingsBoard | docker stop mytb |
| 进入容器内部 | docker exec -it mytb bash |
| 删除容器（危险：数据在宿主机目录，不会丢失） | docker rm -f mytb |
3. 数据备份与恢复
- 备份 ：直接打包宿主机的
~/.thingsboard-data目录即可。建议每日定时备份。 - 恢复 ：停止并删除当前容器，将备份的数据恢复到
~/.thingsboard-data，再重新执行docker run命令。
🔗 五、 与 EMP 项目集成 (Spring Boot)
在 EMP 项目的 application-local.yml 中配置连接：
yaml
iot:
hub:
host: http://192.168.21.16:9090
username: tenant@thingsboard.org
password: tenant💡 避坑提示：
- 如果 EMP 项目运行在本地 Windows，而 ThingsBoard 运行在 Linux 服务器，
host必须填服务器的实际 IP（192.168.21.16），不能填localhost。 - 确保服务器的
9090端口在防火墙中是放行的（如果是内网，建议直接关闭 firewalld 或配置 IP 白名单）。 - 如果报
Connection timed out，请先在本地电脑浏览器访问http://192.168.21.16:9090确认网络连通性。
❓ 六、 常见问题排查 (FAQ)
Q1：浏览器打不开 9090 端口？
A：检查服务器防火墙（firewall-cmd --list-ports），检查容器是否在运行（docker ps），检查 ThingsBoard 日志是否有报错。
Q2：日志一直报 Connecting to Postgres...？
A：说明内置的 PostgreSQL 没有初始化成功，通常是挂载目录的权限问题。执行 chmod -R 777 ~/.thingsboard-data 后重启容器。
Q3：容器启动后自动退出？
A：可能是内存不足导致被系统 Kill，或者挂载目录权限错误。使用 docker logs mytb 查看退出前的报错。
文档创建时间：2026-10-09
维护人：你的名字
下一步建议 ：ThingsBoard 已就绪，赶紧回到 IDEA 中，把 EMP 项目的 iot.hub.host 改为 http://192.168.21.16:9090，重新启动你的 Spring Boot 项目。之前那个 restClient 连接超时的错误一定已经消失了！如果启动还有别的问题，随时发日志给我。