1. 场景与方案选型
1.1 这个需求是从哪来的
先说清楚这个事情的背景。ThingsBoard大家应该不陌生，开源的物联网平台，设备接入、数据可视化、规则链告警一套东西做得挺完整。但问题在于，它默认的接入方式基本是MQTT、CoAP、HTTP这些物联网协议，面向的是传感器、网关、边缘盒子这类“会说话”的设备。可实际干活的时候，你手里经常有一些“不会说话”的数据源——比如一套老旧的MES系统、一个历史数据库、一张几百兆的Excel导出的业务表。这些数据也想进ThingsBoard做看板、做告警，怎么办？
tb-gateway就是ThingsBoard官方出的一个协议转换网关，专门干这事。它能把各种非标准协议翻译成ThingsBoard能听懂的MQTT/HTTP消息。ODBC是微软定义的数据库访问标准接口，几乎所有主流数据库——MySQL、PostgreSQL、SQL Server、Oracle、甚至国产的达梦、人大金仓——都提供ODBC驱动。把ODBC数据源接进tb-gateway，就等于让ThingsBoard平台直接“读取”老数据库里的业务数据，把一堆历史存量数据变成实时更新的遥测，这条路我实际搭过几次，确实能走通。
有一回在某工厂做项目，客户要求把产线上的一套老旧PLC采集数据库（存在SQL Server里）的数据同步到ThingsBoard大屏上做实时展示。PLC那边没人敢动，数据库却是随便读的。我当时第一个念头就是让tb-gateway定期轮询这张表，把新插入的产量记录转成遥测推送上去。实测下来，从配置到跑通大概花了半天，后面大屏的数据基本就是跟着产线走了。这就是典型场景：不动原有业务系统、不装额外采集程序、只靠数据库只读账号就把数据接进来了。
1.2 为什么用tb-gateway而不是别的
有人肯定会问：我直接在ThingsBoard上用规则链的REST API回调去查数据库行不行？或者我自己写个脚本把数据推给MQTT行不行？都能，但我实际对比之后发现，用tb-gateway有几个很实际的好处。
第一，它是ThingsBoard官方组件，版本跟着主平台走，协议适配不用自己维护。规则链的REST API回调查询，你得自己管HTTP端点、鉴权、失败重试，更关键的是规则链的执行模型是事件驱动的，不适合做“定时轮询拉数据”这种活，写起来很别扭。自己写脚本推MQTT，灵活性确实高，但设备接入、断线重连、数据持久化这些全都得自己造轮子，维护成本一下就上去了。
第二，tb-gateway本身就带了设备管理、遥测上报、属性上报的标准封装。你从ODBC读到的每一行数据，只要按它的格式组织好，网关就会自动帮你转换成ThingsBoard支持的设备遥测消息。数据到了平台之后，所有可视化、告警、规则链功能直接就能用，不用做二次开发。
第三，也是我推荐的核心原因——tb-gateway支持自定义扩展。它的ODBC接入功能是通过一个独立扩展包（tb-gateway-odbc）提供的，本质上是在网关里跑一个小型Python运行时，通过pyodbc连接数据库，再用转换函数把查询结果映射成设备消息。这个架构意味着你能写自己的数据转换逻辑，不只是简单的“搬运”，而是可以在中间做清洗、聚合、字段重命名。
这套方案适合谁？适合手里有现成关系型数据库、想把数据送进ThingsBoard做可视化或告警的开发者。如果你只是接几台MQTT设备，那没必要绕这一圈；但一旦涉及存量系统数据接入，tb-gateway的ODBC扩展基本是成本最低的路线。
2. 前置准备与工具链梳理
2.1 需要准备哪些软件
先把要用的东西列个清单，免得后面配置的时候才发现缺东少西。
- ThingsBoard平台：我用的是社区版3.3.x，理论上3.2以上都行。你要先有一个能访问的ThingsBoard实例，本机装一个或者用现成的都无所谓，关键是待会儿要在上面创建设备。
- tb-gateway：独立于平台之外跑的网关程序。可以从官方GitHub的Release页面下载编译好的二进制包，支持Linux和Windows。我建议直接用Docker跑，省去一堆依赖问题。
- ODBC扩展：tb-gateway-odbc，这是一个Python扩展包，需要安装到tb-gateway的扩展目录里。官方文档把这个功能叫做ODBC Connector，社区版和商业版都支持。
- 数据库ODBC驱动：比如你连SQL Server，就装微软的ODBC Driver 17 for SQL Server；连MySQL就装MySQL Connector/ODBC。这一步最容易漏，很多人配置半天连不上，最后发现是驱动没装。
- 一个趁手的数据库客户端：看数据、测SQL用。我用DBeaver比较多，免费且连接信息一目了然。
版本选择上有个小提醒：tb-gateway的每个版本对应特定的ThingsBoard版本，比如tb-gateway 3.3.x对应ThingsBoard 3.3.x。不是说严格一一对应就行，太老的网关连新平台偶尔会出兼容问题，所以装之前先看一眼Release说明，选一个跟平台版本匹配的。
2.2 系统环境的几个坑
先说操作系统。如果你用Linux，网关和扩展装起来比较顺，依赖用包管理器就能搞定。Windows上也能跑，但有个坑：pyodbc在Windows下会依赖系统级ODBC驱动管理器，驱动装不好就会报错。
环境变量也是一个容易被忽略的点。ODBC扩展是Python写的，它通过环境变量找ODBC驱动的配置。Linux下通常要确保ODBCSYSINI指向/etc，让pyodbc能找到odbcinst.ini文件。我第一次配置的时候，驱动装上去了，但odbcinst.ini里驱动条目名字写错了，导致网关启动时报“Data source name not found”，排查了很久才发现就是大小写不对。这个文件里的驱动名一定要和代码里引用的名字完全一致，包括大小写，别小看这个问题。
再说Python运行时。tb-gateway-odbc是基于Python 3写的，网关本身内置了一个Python运行时，安装扩展的时候要确认扩展放到了网关的extensions目录下，并且目录结构正确。官方文档写得很清楚，但实际很多人图省事把文件解压到别处，结果网关启动时根本不加载这个扩展。我后来都是直接看网关日志里的扩展加载记录来确认，有没有加载成功一眼便知。
3. 网关配置与连接器实现
3.1 安装tb-gateway-odbc扩展
整个过程可以拆成三步：装网关、装扩展、配连接器。网关的安装我就不赘述了，不管是二进制包还是Docker，跑起来之后能看到基本日志输出就算成功。装扩展这一步，关键是把tb-gateway-odbc的压缩包解压到正确的扩展目录。
用Docker运行的话，扩展目录通常是通过卷挂载进去的，比如你是用thingsboard/tb-gateway镜像跑的，可以把扩展包解压到本机的某个目录，再挂载到容器内的/thingsboard/extensions。直接改Docker Compose文件里的volumes配置就行。
我自己常用的做法是先在宿主机建一个/opt/tb-gateway-extensions目录，把下载的ODBC扩展解压进去，然后在docker-compose.yml里加上一行挂载：
volumes: - /opt/tb-gateway-extensions:/thingsboard/extensions另外还需要把数据库驱动库放进容器里。ODBC扩展在容器里运行，需要访问宿主机的ODBC Driver Manager，所以还要挂载本机的ODBC配置：
volumes: - /etc/odbc.ini:/etc/odbc.ini - /etc/odbcinst.ini:/etc/odbcinst.ini挂载好之后，启动网关，看日志里有没有“OdbcConnectorExtension loaded”类似的输出。有，就说明扩展装好了。
3.2 写好connector.json
这是整个接入过程最核心的文件。tb-gateway启动时会读取扩展目录下的connector.json，这个文件告诉网关：怎么连数据库、多久轮询一次、把查询结果映射成什么设备消息。
先看一个最简配置，目标是连接一个本机的PostgreSQL数据库，每隔10秒钟读取一次device_data表里的最新数据：
{ "connectors": [ { "name": "Postgres Odbc Connector", "type": "odbc", "configuration": { "pollingInterval": 10, "connectionString": "Driver={PostgreSQL Unicode};Server=127.0.0.1;Port=5432;Database=mydb;Uid=myuser;Pwd=mypass;", "mapping": [ { "deviceName": "device_${device_id}", "deviceType": "default", "query": "SELECT device_id, temperature, humidity, ts FROM device_data WHERE ts > ${lastPollTime} ORDER BY ts ASC", "telemetry": [ {"key": "temperature", "type": "double"}, {"key": "humidity", "type": "double"} ], "attributes": [ {"key": "device_id", "type": "string"} ] } ] } } ] }逐个字段说。pollingInterval是轮询间隔，单位秒。connectionString是ODBC连接串，每个数据库都不一样，关键是Driver名字要和odbcinst.ini里的一致。
mapping是一个数组，表示“一类查询对应一组设备消息”。deviceName支持模板变量，比如device_${device_id}就是把查询结果里device_id字段的值动态拼到设备名里。deviceType是设备类型，平台侧会自动创建设备。
query就是查询语句。注意这里有个很关键的变量${lastPollTime}，它代表上一次轮询的时间戳。每次轮询之后，网关会自动记录这次轮询的时间，下次进来替换这个变量，实现增量查询。这个机制是避免重复上报的基石，后面详说。
telemetry和attributes定义字段映射：查询结果里的列名如果和key对应，就自动取出来作为遥测或属性上报。遥测走的是数据流，属性走的是设备配置信息，区别在于遥测会进时序数据库，适合温度、湿度这种不断变化的值；属性放的是不太变化的静态信息，比如设备ID、位置。
3.3 转换函数怎么写
配置里的字段映射能解决90%的简单场景，但真遇到需要复杂转换的时候，就得写转换函数了。tb-gateway-odbc支持在配置里指定一个Python函数，对查询结果的每一行做自定义处理。
这个函数的逻辑很直白：输入是一行数据库记录和连接器上下文，输出是一个包含设备消息的列表。比如你有一个raw_data表，里面温度和单位混在一起，就要在函数里解析。
def convert(msg, context): res = [] row = msg device_name = "device_" + str(row["device_id"]) telemetry = { "temperature": float(row["temp_value"]), "record_ts": int(row["ts"]) } attributes = { "source_table": "raw_data" } res.append({ "deviceName": device_name, "deviceType": "default", "telemetry": telemetry, "attributes": attributes }) return res这个函数的强大之处在于，它是在网关内部执行的，你可以在这里做任意处理：单位换算、字符串清洗、异常值过滤、甚至调用外部API补充数据。我做过一个场景，数据库里气温是华氏度，前端大屏要摄氏度，就是在转换函数里先减32再乘5/9，改起来只动了这一处，不用动数据库。
转换函数写好之后，在connector.json里这样引用：
{ "converter": { "type": "custom", "extension": "my_converter", "function": "convert" } }其中extension是扩展模块名称，function是函数名。这里要保证扩展的Python文件放在网关能识别到的位置，否则启动时会报转换函数找不到的错误。
4. 数据映射与多表场景实战
4.1 单表轮询怎么设置
最典型的使用方式，就是定时轮询一张业务表，把新增数据上报到ThingsBoard。这里有几个经验值得分享。
第一，轮询间隔不是越短越好。我见过有人把pollingInterval设成1秒，数据库瞬时压力上去了，但其实很多业务数据根本不需要这么高频。PLC产线数据一般1秒或5秒就够用了，环境传感器这类可能10秒甚至1分钟都行。设置之前想清楚业务侧的真实需求，别给自己找麻烦。
第二，建议在查询语句里加ORDER BY ts ASC，配合${lastPollTime}保证抓取顺序。否则如果数据插入顺序和主键顺序不一致，容易漏数据或者乱序上报。增量查询的条件一般用WHERE ts > ${lastPollTime}，这里的ts可以是任意自增时间字段，但必须是单调递增的，否则会漏行。
第三，轮询间隔和查询时间窗口要协调。假设你设了10秒轮询，但某次数据库卡了5秒才返回结果，下次轮询已经开始了，就可能出现重入。网关对这种情况有基本的串行保护，但如果你手动在数据库里插入了一批几千行的历史数据，一次性查出来就要花不少时间，中间如果还有新数据进来，就可能被这次查询吞掉。所以自增ID配合时间戳做增量条件更稳，比如：
WHERE id > ${lastId} AND ts > ${lastPollTime}这种方式我实测下来最不容易出问题。
4.2 多表多设备怎么拆
你可能会遇到另一种情况：数据库里有好几张表，分别对应不同的设备类型，想上报到不同的ThingBoard设备上。一个connector.json里可以配置多个mapping对象，每个mapping对应一张表的轮询和映射规则。
比如一个环境监控项目，有weather_station表和air_quality表，希望分别上报给两个设备。可以这样配：
"mapping": [ { "deviceName": "weather_station_${station_id}", "deviceType": "weather", "query": "SELECT station_id, temperature, humidity, pressure, ts FROM weather_station WHERE ts > ${lastPollTime}", "telemetry": [ {"key": "temperature", "type": "double"}, {"key": "humidity", "type": "double"}, {"key": "pressure", "type": "double"} ] }, { "deviceName": "air_quality_${sensor_id}", "deviceType": "air_monitor", "query": "SELECT sensor_id, pm25, pm10, ts FROM air_quality WHERE ts > ${lastPollTime}", "telemetry": [ {"key": "pm25", "type": "double"}, {"key": "pm10", "type": "double"} ] } ]这样配好之后，一个网关就同时承担了两类“虚拟设备”的数据上报，平台侧会自动创建设备，无需手动在界面上逐个添加。实测下来很稳，关键点就是每个mapping的deviceName模板要能唯一区分设备，如果多张表拼接出来的设备名撞了，数据就乱了。
4.3 增量同步防重复
增量同步是这类轮询方案里最容易被坑的环节。我最初做的时候，没想太多，直接用WHERE ts > ${lastPollTime}，结果测试时发现每条数据都被上报了两次。查了半天才明白机制：${lastPollTime}记录的是“上次轮询开始的时间”，而不是“上次成功处理完最后一条数据的时间”。如果你的查询执行得很快，数据库又很闲，两次轮询之间的时间差很小时，边界上的数据就可能被重复读取。
解决办法有几个层面。最直接的是把增量条件改成基于自增主键：
WHERE id > ${lastId}网关支持自定义状态变量，你可以在转换函数里自己维护lastId。举个简单的例子，在函数里记录本次查询到的最大ID，存到上下文中，下次查询时用这个值作为起点。
def convert(msg, context): max_id = msg["id"] context["lastId"] = max_id ...另一个更省事的办法是，给表加一个processed标记字段。但业务表一般不愿意为接入这事改结构，所以我还是推荐自增ID方案。如果表里既没有自增ID也没有单调递增时间字段，那就只能在转换函数里做去重了——在网关上维护一个缓存ID集合，超过一定数量的旧ID就丢掉。这个方案内存压力小，逻辑还简单，适合一次性同步大量历史数据的场景。
5. 与ThingsBoard的联动玩法
5.1 遥测与属性怎么映射
数据到了平台侧，接下来就是怎么用的事了。先说遥测和属性的差异：遥测是可以画曲线、做阈值告警的时序数据，属性则更像设备的静态档案。
拿工厂那个案例来说，temperature、pressure这类每秒钟都在变的值走遥测，station_id、location走属性。这样在前端看板里，曲线图拉出来的就是平滑的温度趋势，而设备的元信息在设备详情页一翻就能看到。
映射关系在connector.json里通过telemetry和attributes两个列表控制。注意网关上报的时候，默认是把某一次查询得到的多行数据分别处理，每行生成一条独立的遥测消息。ThingsBoard的时序存储天然支持乱序写入，所以即便某次轮询返回的行时间戳有先后差异，平台这边也能按时间戳正确排序。
5.2 规则链和设备配置
数据进来之后，要真正产生价值，还得配合ThingsBoard的规则链。比如温度超过80度就触发告警，这种逻辑不用写代码，在规则链里拖几个节点就能搞定。
我的做法是，先创建一个规则链，入口节点配置为“消息类型”等于POST_TELEMETRY，然后接一个脚本节点判断字段值。脚本很简单，一个条件表达式就够了。再往下接一个“创建告警”节点，填上告警类型和严重级别就行。
设备这边，如果网关上报的deviceName是动态拼接的，平台会自动创建设备。有时候你想要一个真实的设备档案，比如型号、位置、维护人这类信息，可以在平台侧手动编辑这个自动创建设备的属性。但要注意，如果网关下一次上报的设备名还是同一个，会自动复用这个设备，不会重复创建。
另外提醒一句，默认情况下ThingsBoard社区版对新接入的设备是放开的，但如果你开了设备配置管理，可能需要在设备配置里允许自动创建设备，否则上报会被拒。这个坑我踩过一次，折腾半天才发现是配置里少了开关。
6. 常见问题与排查速查表
做了几次ODBC接入之后，我把踩过的坑整理成了一张速查表，分享出来。
6.1 连接失败与超时
Connection string里的Driver名不对，是最常见的。确保odbcinst.ini里的驱动名和连接串里的Driver完全一样，包括大小写和空格。
数据库不在本机的话，注意防火墙和安全组。ODBC默认端口因数据库而异，PostgreSQL是5432，MySQL是3306，SQL Server是1433。如果你在容器里跑网关，还要确认网关容器能访问到数据库所在网段。
轮询超时主要是因为查询太慢。如果单次查询超过pollingInterval，就会积压，继而引发重复查询。解决办法是给查询加LIMIT限制每次抓取行数，比如LIMIT 1000，分多次抓完，时间窗口可以重叠但配合自增ID不会漏。
6.2 数据上不去
数据上不去，先看网关日志。关键字“telemetry sent”表示上报成功，“error”后面跟着的就是原因。常见错误有几种：
device not found：说明网关上报的设备名在平台侧不存在，同时自动创建设备的功能没开。去设备配置里把允许自动创建打开，或者手动在平台创建一个对应名称的设备。invalid telemetry format：字段类型不匹配。我在某次配置里把temperature设成了int，但数据库里是浮点数，结果全被过滤了。改成double就正常。query returned 0 rows：这是正常情况，说明没有新数据，可以不管。
6.3 网关崩溃
网关崩溃最头疼。主要集中在内存泄漏和库依赖冲突两块。ODBC扩展本身是Python写的，如果转换函数里写了不合理的循环或缓存，内存慢慢涨上去，跑个一两天就崩了。我给一个客户排查过类似问题，最后发现是他在转换函数里每次调用都打开了一个数据库连接，然而从不释放，连接数爆掉了。
稳定运行的建议：
- 转换函数保持轻量，只做必要的数据处理，不要在里头查库、发HTTP请求。
- 网关的Docker容器设置合理的资源限制，比如
mem_limit: 512m，避免内存涨满影响宿主机。 - 给容器加上
restart: always策略，万一崩了能自动拉起来。 - 定期重启策略也可以加上，比如每天凌晨4点重启一次，实测对内存泄漏有奇效。
7. 一些想说的经验
ODBC接入这条链路，我第一次搭的时候也怀疑过：一套纯数据库轮询的方案，能不能满足实时性要求？实际做下来发现，只要表结构设计得合理、轮询间隔匹配业务需求，完全能承担生产级别的数据同步。很多工厂项目要求的实时性也就是秒级，轮询完全够用。
我个人在实际操作中的体会是，这类数据接入的瓶颈通常不在工具，而在存量数据本身的质量问题。比如字段类型不一致、时间戳格式混乱、数据有空洞，这些脏数据问题会直接影响到表结构设计和增量查询方案。所以开工之前先花半天搞清楚表结构、数据分布、主键自增情况，后面能少加三天班。
最后再分享一个小技巧：在正式接入之前，先写一条独立的SQL，把表里最近一天的数据拉出来，然后对照字段映射逐个核对类型。这一步基本能把九成以上的配置错误提前暴露掉。接入不是目的，能让数据持续稳定地流动起来才是目的，前期多花点时间做数据摸底，绝对值得。
