ThingsBoard 租户数据迁移工具 tb-migrator:Cassandra/PostgreSQL 数据导出与导入实战指南
物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载ThingsBoard 的tb-migratorMigrator Application是面向租户级数据迁移的专用工具它能把指定租户在 PostgreSQL 中存储的全部实体设备、资产、规则链、仪表盘、告警等以及存储在 Cassandra或 PostgreSQL中的时序数据TS/KV、最新 KV 数据完整导出为一个数据归档再原样导入到另一套 ThingsBoard 环境。本指南围绕仓库中的 migrator 模块 README 展开结合源码讲解MIGRATOR_MODE、SKIPPED_TABLES、Cassandra TTL 等核心参数并给出可直接复制的 Docker 运行命令与典型 env 配置读完你就能独立完成一次“导出 → 跨环境 → 导入”的租户数据搬迁。一、迁移工具是什么从架构看工作方式tb-migrator是一个独立的 Spring Boot 应用模块位于仓库 migrator/运行时入口为 MigratorApplication.java。其运行逻辑非常清晰启动时通过MIGRATOR_MODE环境变量决定当前是导出模式还是导入模式打开数据归档存储Storage依次执行所有启用的MigrationService全部完成后关闭归档进程默认自动退出exit_after_finish默认true。从 MigrationService.java 源码可以看到每个迁移服务都使用一个大小为parallelism_level的固定线程池线程命名形如migrator01、migrator02按stats_print_interval周期打印处理进度Processed: 123/456 (27%)方便在大数据量下观察迁移状态。工具的四种核心工作模式对应如下MIGRATOR_MODE作用对应源码实现TENANT_DATA_EXPORT导出指定租户的 PostgreSQL 实体数据可选导出 Cassandra 时序历史PostgresTenantDataExporter.java、CassandraTsKvExporter.javaTENANT_DATA_IMPORT将导出的归档导入目标环境PostgresTenantDataImporter.java、CassandraTsKvImporter.javaCASSANDRA_LATEST_KV_EXPORT单独导出 Cassandrats_kv_latest_cf最新 KV数据CassandraLatestKvExporter.javaCASSANDRA_LATEST_KV_IMPORT单独导入最新 KV 数据latest_kv导入服务与导出对称注原文档 README 给出了导出与导入两类完整配置CASSANDRA_LATEST_KV_EXPORT/IMPORT为源码中额外提供的独立模式用于只迁移“最新遥测值”而不迁移完整历史。二、导出租户数据Docker 运行与 env 配置详解README 给出的导出运行命令为docker run -v ./migration-data:/tb-migrator/data --env-file tb-migrator.env thingsboard/tb-migrator:latest其中两个关键点-v ./migration-data:/tb-migrator/data把宿主目录挂载到容器内/tb-migrator/data即工具的working_directory导出的归档文件会落在该目录Dockerfile 中已预先创建并授权/tb-migrator/data--env-file tb-migrator.env从本地 env 文件注入全部配置避免把数据库口令写进命令行。对应的导出 env 文件即 README 中的导出示例MIGRATOR_MODETENANT_DATA_EXPORT EXPORTED_TENANT_IDTENANT_ID SKIPPED_TABLESRULE_NODE_DEBUG_EVENT,STATS_EVENT,LC_EVENT DATABASE_URLjdbc:postgresql://POSTGRES_HOST:5432/thingsboard DATABASE_USERNAMEpostgres DATABASE_PASSWORDpostgres CASSANDRA_EXPORT_ENABLEDtrue CASSANDRA_URLCASSANDRA_HOST:9042 CASSANDRA_LOCAL_DATACENTERus-east CASSANDRA_KEYSPACE_NAMEthingsboard2.1 核心参数逐项说明MIGRATOR_MODETENANT_DATA_EXPORTSpring 通过${mode}表达式激活对应的导出 Bean。以 PostgresTenantDataExporter.java 为例其激活条件为${mode} TENANT_DATA_EXPORT export.postgres.enabled trueCassandra 导出器的条件则是export.cassandra.enabled true见 CassandraTsKvExporter.java。注意README 的示例 env 中没有显式写POSTGRES_EXPORT_ENABLED但源码默认导出 PostgreSQL 实体若你的部署在 Postgres 实体之外还用 Cassandra 存时序则必须设CASSANDRA_EXPORT_ENABLEDtrue。EXPORTED_TENANT_IDTENANT_ID指定要导出的租户 UUID映射到源码中的export.tenant_idPostgresTenantDataExporter.java。它是导出查询的唯一租户过滤条件。SKIPPED_TABLESRULE_NODE_DEBUG_EVENT,STATS_EVENT,LC_EVENT逗号分隔的表名列表用于跳过不必要的数据。这三个都是调试/统计类事件表rule_node_debug_event、stats_event、lc_event数据量大且对业务无实际价值默认建议跳过。表名必须在 Table.java 定义的枚举中源码解析为SetTablePostgresTenantDataExporter.java未知表名会在启动时失败。该枚举覆盖了 50 张表包括tenant、customer、device、asset、rule_chain、dashboard、alarm、user、widgets_bundle等全部业务实体。DATABASE_URL / DATABASE_USERNAME / DATABASE_PASSWORDPostgreSQL 连接信息DATABASE_URL使用 JDBC 格式jdbc:postgresql://host:5432/thingsboard。CASSANDRA_EXPORT_ENABLEDtrue启用 Cassandra 时序历史导出。仅当目标环境的时序数据存放在 Cassandra 时需要开启。CASSANDRA_URLCASSANDRA_HOST:9042Cassandra contact points多个节点用逗号分隔。对应 CassandraConfig.java 中 Spring Boot 的 Cassandra 自动配置spring-boot-starter-data-cassandra见 pom.xml。CASSANDRA_LOCAL_DATACENTERus-eastCassandra 本地数据中心名称必须是集群实际配置的 DC 名否则驱动无法建立连接。CASSANDRA_KEYSPACE_NAMEthingsboardCassandra keyspace 名称即 ThingsBoard 时序表所在的 keyspace。2.2 导出流程源码中的实现细节导出过程分两步走第一步Postgres 实体导出PostgresTenantDataExporter.java 遍历Table.values()对每张表按租户 ID 构造WHERE tenant_id TENANT_ID查询对没有tenant_id列但有关联关系的表如user_credentials通过user_id关联tb_user、entity_group通过owner_id关联 tenant/customer会生成IN (SELECT id FROM ... WHERE tenant_id ...)子查询。关联表RELATION关系、ATTRIBUTEattribute_kv属性、LATEST_KVts_kv_latest会针对每个实体单独导出。查询按batch_size分页LIMIT x OFFSET y批次间按delay_between_queries休眠避免对源库造成过大压力PostgresTenantDataExporter.java。ota_package表中的大字段固件会被转成 blob 特殊格式导出。第二步Cassandra 时序导出CassandraTsKvExporter.java 先读取第一步导出的ts_kv_latest归档逐条获取(entity_type, entity_id, key)组合再查询ts_kv_partitions_cf得到该 key 的每个 partition最后从ts_kv_cf拉取完整历史。它还支持按时间范围过滤export.cassandra.ts.filter.start_ts/end_tsepoch 毫秒可只导出某时间窗内的数据export.cassandra.ts.filter.partition_ts可只导出指定 partition。所有导出数据先经 Storage.java 的 GZIP 压缩写出为xxx.gz文件最终在close()阶段打包成一个data.tar归档文件Storage.java。因此挂载目录里最终只会看到data.tar直接将其拷贝到目标环境即可。三、导入前的关键前提先创建再删除一个临时租户README 特别强调了一条硬性前置条件Before importing, make sure to create (and then delete) a tenant so that system roles are created.导入之前必须先在目标环境创建一个临时租户、再将其删除目的是让系统角色system roles如 Tenant Administrators在目标数据库中完成初始化。原因是导入的数据如group_permission表会引用这些系统角色 ID而这些角色只有在租户创建流程中才会被生成。这一点在源码 PostgresTenantDataImporter.java 中也有印证导入group_permission时若role_id在role表中不存在默认会直接抛异常只有开启resolve_unknown_roles才会按role_name回查匹配。所以先创建/删除一次临时租户保证目标库角色齐备是最稳妥的路径。四、导入租户数据env 配置与执行README 给出的导入 env 文件示例MIGRATOR_MODETENANT_DATA_IMPORT SKIPPED_TABLESRULE_NODE_DEBUG_EVENT,STATS_EVENT,LC_EVENT POSTGRES_IMPORT_ENABLEDtrue DATABASE_URLjdbc:postgresql://POSTGRES_HOST:5432/thingsboard DATABASE_USERNAMEpostgres DATABASE_PASSWORDpostgres CASSANDRA_IMPORT_ENABLEDtrue CASSANDRA_IMPORT_TS_KV_TTL730 CASSANDRA_URLcassandra:9042 CASSANDRA_LOCAL_DATACENTERus-east CASSANDRA_KEYSPACE_NAMEthingsboard运行命令与导出一致把data.tar放进挂载目录后执行docker run -v ./migration-data:/tb-migrator/data --env-file tb-migrator.env thingsboard/tb-migrator:latest导入启动时Storage.open() 会自动把data.tar解包回各表的.gz文件再逐表读取。4.1 与导出不同的参数POSTGRES_IMPORT_ENABLEDtrue显式启用 PostgreSQL 实体导入PostgresTenantDataImporter.java 的激活条件为${mode} TENANT_DATA_IMPORT import.postgres.enabled trueCASSANDRA_IMPORT_ENABLEDtrue启用 Cassandra 时序历史导入CASSANDRA_IMPORT_TS_KV_TTL730给导入的 Cassandra 时序数据统一设置TTL单位天默认 730 天 ≈ 2 年。源码中对应import.cassandra.ttl_days写入ts_kv_cf与ts_kv_partitions_cf时都会追加USING TTL seconds见 CassandraTsKvImporter.java。若想永久保留数据可将其设为较大的值或改为 0 以禁用 TTL需确认源码对该值的处理符合预期。导入端同样支持import.cassandra.skip_lines跳过前 N 行用于断点续传场景见 CassandraTsKvImporter.java。4.2 导入流程源码中的细节处理PostgresTenantDataImporter.java 将整个导入包在一个事务里执行并做了几件关键的事动态建分区对分区表如rule_node_debug_event、audit_log、event系列在enable_partition_creation开启时自动创建缺失的分区PostgresTenantDataImporter.javakey 字典重建导入attribute_kv/ts_kv_latest时会把导出文件中的key_name转回目标库的key_dictionary.key_id不存在则插入新 key见 PostgresTenantDataImporter.java未知列容错若归档中存在目标库没有的列会跳过并打印Skipping unknown column ...警告PostgresTenantDataImporter.java这使低版本→高版本的迁移也能部分兼容临时解除外键导入前先ALTER TABLE ota_package DROP CONSTRAINT fk_device_profile_ota_package结束后再重新加上避免导入顺序导致的外键冲突PostgresTenantDataImporter.java。Cassandra 导入端则按(entity_type, entity_id, key, partition)去重维护分区表写入并使用线程池并发执行 INSERT配合 CassandraService.java 内置的指数退避重试max_retries默认 10 次、initial_delay100ms、multiplier2.0与错误率限速机制能扛住导入高峰期的偶发超时。五、可选增强参数与运行注意事项除了 README 列出的参数从源码和配套脚本可以补充以下实用项与 README 同级的补充示例见 msa/migrator/README.mdWORKING_DIRECTORY/tmp/tb-migration/data自定义工作目录映射working_directory配置目录会自动创建Docker 方式下即挂载卷的容器内路径PARALLELISM_LEVEL4并发线程数对应 MigrationService.java 中的parallelism_level值越大导出/导入吞吐越高但会给源/目标数据库带来更大压力建议结合数据库能力调整POSTGRES_EXPORT_ENABLEDtrue显式声明启用 Postgres 实体导出README 导出示例中省略时默认生效STATS_PRINT_INTERVAL进度统计打印间隔源码默认按配置读取用于控制日志刷屏频率。运行注意事项导出与导入的SKIPPED_TABLES必须保持一致否则导入端会因缺少某表的数据文件而报错MIGRATOR_MODE是模式开关导出/导入模式下的EXPORTED_TENANT_ID、CASSANDRA_EXPORT_ENABLED等参数各有不同语义复制配置时注意区分迁移涉及大量写入导入到 Cassandra 的 TTL 一旦设定到期数据会被自动清除务必按业务留存要求设置工具默认在迁移完成后自动退出exit_after_finishtrue适合容器化一次性执行迁移前建议为目标环境做数据库备份并先在测试环境完整跑一遍导出/导入验证设备数据、仪表盘、告警等是否完整。六、小结一份可复用的迁移清单以 README 为核心结合源码可以归纳出一次完整迁移的标准动作源环境准备导出 envMIGRATOR_MODETENANT_DATA_EXPORTEXPORTED_TENANT_IDSKIPPED_TABLES Postgres/Cassandra 连接信息执行docker run -v ./migration-data:/tb-migrator/data --env-file tb-migrator.env thingsboard/tb-migrator:latest目标环境先创建再删除一个临时租户保证系统角色初始化传输将挂载目录中的data.tar拷贝到目标机器目标导入把data.tar放入目标挂载目录准备导入 envMIGRATOR_MODETENANT_DATA_IMPORTPOSTGRES_IMPORT_ENABLEDCASSANDRA_IMPORT_ENABLEDCASSANDRA_IMPORT_TS_KV_TTL再次执行同样的 Docker 命令校验观察日志中的Processed: xxx/xxx (xx%)进度直至Finished successfully!再到 UI 中核对该租户的设备、数据与仪表盘。这就是 ThingsBoard 租户级数据搬迁的完整闭环——README 给出的命令与配置可直接投产源码则保证每一步都有据可查。赞分享物联网后端数据可视化消息队列【免费下载链接】thingsboardAll-in-one IoT Platform - Device management, data collection, processing and visualization.项目地址https://gitcode.com/GitHub_Trending/th/thingsboard点击查看免费下载相关推荐ThingsBoard tb-migrator 租户数据迁移工具实战指南Docker 部署、环境变量配置与源码原理ThingsBoard tb migrator 租户数据迁移工具实战指南Docker 部署、环境变量配置与源码原理 导读 本文以 ThingsBoard 开源物联网后端数据可视化消息队列3步搞定数据迁移Prisma1数据导入导出工具实战指南3步搞定数据迁移Prisma1数据导入导出工具实战指南 Prisma1作为现代化的数据库框架和ORM提供了便捷的数据导入导出功能帮助开发者轻松实现数据迁移后端数据库GraphQLMongoDB数据导出导入node-express-boilerplate数据迁移工具MongoDB数据导出导入node express boilerplate数据迁移工具 在开发和运维过程中数据迁移是常见需求尤其对于使用MongoDB作为后端创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

相关新闻

学 LangChain 前三章,我悟了:别人的理解永远是别人的,自己写一遍才是自己的

学 LangChain 前三章,我悟了:别人的理解永远是别人的,自己写一遍才是自己的

为什么写这篇 跟着视频学 LangChain,敲完代码觉得"哦我懂了"。真让我合上教程操作一遍,手下的代码总是泛红 于是我干了件事:拿笔记本,把前三章的知识点用自己的话手写一遍。 写的时候才发现:原来我以为懂…

2026/11/17 12:10:25 阅读更多 →
为什么你的纸袋热封总是虚封、粘不牢?

为什么你的纸袋热封总是虚封、粘不牢?

纸袋热封过程中常出现虚封和粘不牢的问题、这些问题对包装质量重要。为了确保纸袋在运输和存储过程中不易开口、必须仔细分析虚封等成因。热封温度、施加压力、材料选择和设备设置都是影响热封质量的重要因素。例如,温度不足可能导致热封面未能充分粘合;…

2026/11/14 20:46:00 阅读更多 →
资料总装车间ANDON系统设计落地指南:点位表、SLA与避坑要点

资料总装车间ANDON系统设计落地指南:点位表、SLA与避坑要点

/* MD / 富文本中的 .toc(含博客园搬家等嵌套结构);.toc-box 在侧栏,不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p(:empty 仍占 20px),一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

2026/11/14 2:22:15 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/17 8:22:52 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/16 6:41:34 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/16 8:22:12 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/17 11:26:33 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/16 7:30:18 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/16 8:22:12 阅读更多 →

日新闻

周新闻

月新闻