ThingsBoard PE 从3.8.1升级到3.9.0的数据库版本兼容性问题解决方案

问题背景

在使用Docker部署的ThingsBoard PE环境中，从3.8.1版本升级到3.9.0版本时，系统报错提示数据库版本不兼容。错误信息明确指出当前数据库版本为"3.6.4"，而系统仅支持从[3.8.0, 3.8.1]版本进行升级。

错误现象

升级过程中，系统抛出以下关键错误：

Upgrade failed: database version '3.6.4' is not supported for upgrade. Supported versions are: [3.8.0, 3.8.1].

尽管在.upgradeversion文件中已经正确设置了"3.8.1"版本号，但升级仍然失败，这表明问题出在数据库内部记录的版本信息与实际文件系统记录的版本不一致。

问题根源分析

这种情况通常发生在以下场景：

1. 系统曾经从3.6.4版本升级到3.8.1版本
2. 在升级过程中，文件系统的版本记录已更新，但数据库内部的版本记录未同步更新
3. 3.9.0版本的升级脚本严格检查数据库内部版本号，导致升级失败

解决方案

步骤一：验证数据库当前版本

首先需要连接到ThingsBoard使用的PostgreSQL数据库，执行以下SQL查询确认当前数据库内部记录的版本：

select * from tb_schema_settings;

步骤二：修正数据库版本记录

如果查询结果显示schema_version为3006004（对应3.6.4版本），则需要手动更新为3008001（对应3.8.1版本）：

update tb_schema_settings set schema_version=3008001 where schema_version=3006004;

步骤三：重新执行升级操作

完成数据库版本修正后，重新运行3.9.0版本的升级流程，此时升级应该能够正常进行。

预防措施

为避免类似问题在未来升级时再次发生，建议：

1. 在每次升级完成后，验证数据库tb_schema_settings表中的版本号是否与.upgradeversion文件一致
2. 对于重要升级，先在测试环境验证升级流程
3. 做好数据库备份后再执行升级操作

技术原理

ThingsBoard使用双重版本控制机制：

1. 文件系统记录（.upgradeversion文件）：用于快速检查当前安装版本
2. 数据库记录（tb_schema_settings表）：作为升级脚本执行时的权威版本依据

这种设计虽然提高了安全性，但也可能导致文件系统和数据库版本记录不同步的情况。开发者在设计升级流程时应当确保两种版本控制机制同步更新。