我第一次把 TDengine 和 Docker 放在一起折腾是在一个物联网网关项目里。当时赶上设备数据量暴涨MySQL 的存储和聚合都开始吃力团队临时决定引入时序数据库做试点。网上一搜TDengine 的 docker 安装命令确实看起来简单拉一个镜像、跑一个容器、进去建表三分钟就能用上。但真正跑到业务里才发现docker 安装管理 TDengine 这件事远不止“容器起来了”这么简单多表时序一致性怎么保证、子表和超级表怎么设计、C 程序对接时该不该用 taos_stmt_prepare、甚至刚插入的数据为什么有时候查不到——这些问题每一个都能让人卡上一整天。这篇文章我会从零开始把“docker 安装管理 TDengine”这个主题拆透了来讲。内容覆盖 Docker 环境准备、镜像选型、docker-compose 生产级配置、TDengine 的超级表/子表建模、多表时序一致的实践思路以及 C 绑定写入和常见问题排查。适合物联网开发、后端开发、数据平台运维还有那些正打算把业务从 MySQL 迁到时序数据库的同学。你不需要有多高深的 Docker 基础跟着步骤走就能把一套可用的 TDengine 跑起来同时避开我踩过的那些坑。1. 项目拆解为什么我坚持用 Docker 部署 TDengine1.1 先搞清楚 TDengine 到底是干什么的TDengine 的全称是 Time Series Database直译就是“时序数据库”但它和传统的关系型数据库思路完全不一样。普通数据库把数据看作一张张彼此独立的表而 TDengine 天生服务的是“测点”和“时间线”这类场景一台风机每秒上报一次转速、一组电表每 5 分钟采集一次电压、一辆车每隔 100 毫秒上报一次 GPS 坐标。这类数据的共同特征是写入极频繁、数据量大、时间维度强相关、很少更新删除而且绝大部分查询都是“按时间范围做聚合统计”。你可以把 TDengine 想象成一本严格按时间排序的账本每一行记录都带着时间戳和若干测量值再挂上一组设备维度的标签。在这本账本里建表不是为“某个实体”建而是为“某条测点流”建。这样设计最大的好处是同一批设备的多个测点会天然落在相同的时间结构里查询窗口聚合、降采样、插值都能在数据库内部完成不用像 MySQL 那样靠 group by 硬撑。理解这一点后面对超级表、子表的理解就不会跑偏。1.2 Docker 部署的收益和适用场景官方其实提供了 rpm、deb、源码编译等方式安装 TDengine生产环境里也有不少人直接在物理机或云主机上装原生服务。但我个人在大多数项目中还是默认走 Docker原因很直接依赖隔离。TDengine 的安装过程不是简单的“装完就能用”它涉及服务端 taosd、客户端 taos、配置文件 taos.cfg、数据目录、日志目录、甚至 3.x 版本新增的 taosAdapter 组件。用 Docker 装这些组件全部打进镜像里宿主机上只需要有 Docker 引擎和一块能够持久化数据的磁盘几乎不用关心系统是 CentOS 7 还是 Ubuntu 22.04。Docker 部署还有一个非常实用的价值是“环境可复现”。我在本地用 docker run 调好的参数写进 docker-compose.yml提交到仓库之后同事拉下来 docker compose up -d 就能得到完全一致的环境。这一点对团队协作和测试环境搭建特别重要。当然Docker 也不是万能的。如果你要搭建一个超过 3 节点的高可用 TDengine 集群且对网络延迟和磁盘 IO 有苛刻要求那我还是建议直接用裸机或者 Kubernetes 管理有状态服务Docker 单机模式只适合开发、测试以及中小规模生产。我在下文给的方案就是围绕单机版 docker compose 展开的。2. 环境准备Docker 安装与启动避坑2.1 Docker Desktop 启动失败的几种常见情况很多人第一步就挂在 Docker Desktop 启动上尤其是 Windows 用户。最常见的报错是Docker Desktop failed to start because virtualization support wasnt detected这个报错的原意是 Docker Desktop 依赖虚拟化能力来运行 Linux 容器但系统层面没检测到。我在 Windows 上遇到过三次基本可以按下面顺序排查。第一确认 BIOS/UEFI 里的虚拟化开关已经打开。不同主板名字不一样常见的有 Intel VT-x、AMD-V、SVM Mode一般都在 CPU Configuration 或者 Advanced 菜单里。改完设置要完全断电重启不能只做系统重启。第二Windows 的虚拟机平台和 Hyper-V 功能需要开启。控制面板 - 程序和功能 - 启用或关闭 Windows 功能把 Hyper-V、适用于 Linux 的 Windows 子系统、虚拟机平台 这三项都勾上。第三WSL2 内核需要更新。微软官网有独立的 WSL2 Linux 内核更新包下载安装后重启Docker Desktop 基本就能正常启动了。Linux 桌面环境下还有另一种常见情况Docker 安装成功但普通用户无法执行 docker 命令报错提示 /var/run/docker.sock 权限不足。解决办法是把当前用户加入 docker 用户组sudo usermod -aG docker $USER newgrp docker需要注意的是加入 docker 组等同于给用户 root 级别的容器管理权限这只适合开发机生产服务器上要谨慎。2.2 镜像加速与网络初始化镜像拉不下来、拉得慢是国内使用 Docker 最常见的痛。为解决这个问题Docker 提供了镜像加速配置修改 Docker 引擎的 daemon.json。在 Linux 上路径是 /etc/docker/daemon.json在 Docker Desktop 上可以在 Settings - Docker Engine 里直接编辑。我一般会在这类配置文件里放一个或两个可靠的 registry mirror 地址{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com ] }改完执行systemctl restart dockerLinux或点击 Docker Desktop 的 Apply Restart。这一步不解决所有网络问题但能明显提升 TDengine 这类常用镜像的拉取速度。另外Docker 默认创建的是 bridge 网络容器内容器之间默认可以互联但如果宿主机防火墙策略很严容器访问宿主机或者外部访问容器端口也可能被拦后面第 6 章我会专门讲网络排查。2.3 Docker Compose 的准备Docker Compose 在 Docker Desktop 里默认集成Linux 下则需要单独确认。现在 Docker 官方推荐的是 compose 插件模式命令是docker compose version。如果你的系统里没有可以通过系统包管理器安装sudo apt-get install docker-compose-plugin或者直接按 Docker 官方文档安装 compose v2 插件。我强烈建议用 v2 而不是老的 python 版 docker-compose因为 v2 的配置文件格式和命令行参数更加一致docker compose up -d这种操作在团队内部更好统一。确认好 compose 可用以后就可以进入 TDengine 的实际部署了。3. docker 安装 TDengine从快速验证到生产配置3.1 镜像版本怎么选TDengine 官方镜像名是 tdengine/tdengine。选版本是第一个大坑2.x 和 3.x 的差异非常大2.6 的很多命令和表结构到了 3.x 都不再兼容尤其是超级表的创建语法、客户端连接方式、还有 taosAdapter 的组件化设计。如果你的项目是从零起步直接选 3.x 最新稳定版例如 3.3.x如果是要接手老项目则必须确认原来业务基于哪个大版本不能盲目拉到 latest。另一个容易踩的坑是镜像 tag 的准确写法。latest 虽然方便但无法复现环境。我会在 docker-compose.yml 里固定具体版本号例如tdengine/tdengine:3.3.0.10并把镜像 tag 单独写成一个变量方便后续升级。这样做的好处是线上环境出问题时你能确定容器跑的到底是哪个版本排查日志不至于对着不同版本的 SQL 语法发懵。3.2 一条 docker run 命令做冒烟测试如果是想先快速体验一下不涉及持久化和多容器编排直接用 docker run 完全够用。TDengine 3.x 最需要关心的端口有四个端口用途6030TDengine 原生客户端连接端口taos 命令行、C/C 客户端、JDBC 原生连接6041REST 接口端口HTTP 客户端和很多语言 SDK 默认走这个6043taosAdapter 提供的扩展服务端口6045taosX/Explorer 等 Web 工具端口我一般做冒烟测试会这样跑docker run -d \ --name tdengine \ -p 6030:6030 \ -p 6041:6041 \ -p 6043:6043 \ -p 6045:6045 \ tdengine/tdengine:3.3.0.10启动之后进容器里验证 taos 命令行是否能正常连接docker exec -it tdengine taos看到 taos 的命令行提示符以后先建一个测试数据库和一张最简单的表CREATE DATABASE testdb; USE testdb; CREATE TABLE sensor (ts TIMESTAMP, temperature FLOAT); INSERT INTO sensor VALUES (2025-05-01 10:00:00.000, 36.5); SELECT * FROM sensor;如果这条链路走通说明容器基本正常端口映射也没有问题。冒烟测试用不着的端口可以不开毕竟每个端口都意味着一个暴露面但 6030 和 6041 建议保留。3.3 生产级 docker-compose 配置与数据持久化线上使用就不能只靠 docker run 了我推荐把配置沉淀成 docker-compose.yml。这里有一份我实际在用的模板覆盖了数据卷、日志、时区、重启策略和健康检查version: 3.8 services: tdengine: image: tdengine/tdengine:3.3.0.10 container_name: tdengine hostname: tdengine restart: always environment: - TZAsia/Shanghai ports: - 6030:6030 - 6041:6041 - 6043:6043 - 6045:6045 volumes: - ./tdengine/data:/var/lib/taos - ./tdengine/log:/var/log/taos command: - taosd healthcheck: test: [CMD-SHELL, taos -c /etc/taos/taos.cfg -s show databases || exit 1] interval: 30s timeout: 10s retries: 3 start_period: 30s这里要特别说明持久化。TDengine 的官方镜像把数据放在容器内部的 /var/lib/taos日志放在 /var/log/taos。如果不做卷映射容器一销毁数据全部消失。我把宿主机上的 ./tdengine/data 和 ./tdengine/log 挂载进容器升级镜像、重建容器都不会丢数据。第一次启动之前我还会确认宿主机的挂载目录存在且有权限否则会覆盖成 root 目录进而出现写入问题。本地验证时用docker compose up -d启动用docker compose logs -f tdengine看日志看到类似Vnode is created或者service is ready的日志说明服务启动完成。生产环境里我还习惯给容器加一个 healthcheck方便编排平台感知服务状态。4. 库表设计超级表、子表与多表时序一致4.1 超级表和子表到底怎么建TDengine 里最重要也最容易搞混的概念是超级表STABLE。通俗地说超级表是“模板”子表是“实例”。超级表定义了所有子表共有的数据列和标签列标签列通常用来描述设备属性比如地点、分组、设备型号数据列则是随时间变化的测量值。举个例子我们有 100 台电表每台电表都要记录电流和电压。如果用 MySQL 思路可能会建 100 张表或者一张大表里加设备字段。TDengine 的正确姿势是先建一张超级表再按设备建子表CREATE STABLE meters ( ts TIMESTAMP, current FLOAT, voltage INT ) TAGS ( location BINARY(32), group_id INT );注意这里的 TAGS 和表的字段是分开的。标签列不是普通数据列它用来描述子表的维度属性。然后插入数据时会自动创建子表INSERT INTO d001 USING meters TAGS(Beijing, 1) VALUES (NOW, 12.4, 220); INSERT INTO d002 USING meters TAGS(Shanghai, 1) VALUES (NOW, 8.2, 220);执行之后TDengine 自动为你创建了 d001、d002 两张子表它们都继承了 meters 的列结构标签值分别为北京/上海。查询时你既可以查单张子表也可以直接查超级表后面这种操作可以跨所有设备取数。我在设计表结构时的一个习惯是把不经常变化的设备属性全部放在标签列把随时间变化的物理量放在数据列这能让后续聚合查询效率提升不少。4.2 “多个表时序一致”的落地做法“tdengine 如何做到多个表时序一致”这个热搜词我一直觉得很典型。刚开始接触 TDengine 的同事总会担心不同子表之间的时间戳对不上比如设备 A 的读数在 10:00:00.100设备 B 的读数在 10:00:01.200那窗口聚合时是不是就乱了其实时序一致的基本盘是“以采集时间为主键而不是以入库时间为主键”。TDengine 的数据模型中TIMESTAMP 列就是主键它必须是严格唯一的。只要你在写入时传的是设备真实采集时间戳而不是依赖数据库的当前时间那么不同子表之间的数据天然可以在时间轴上对齐。比如要统计每分钟的平均电流SQL 会写成SELECT _wstart, AVG(current) FROM meters WHERE ts 2025-05-01 00:00:00 AND ts 2025-05-01 00:10:00 INTERVAL(1m);这个 INTERVAL 窗口聚合会把所有子表的数据按分钟切割同一分钟内的电流全部参与平均不会出现 A 表和 B 表时间错位的问题。不过多表真正容易出问题的地方不是查询而是写入端的时间一致性。如果设备时间没有做 NTP 同步每台设备都会按自己的时钟上报即便查询语法是时序对齐的数据本身就错位了。所以我在实际项目中会额外做一层“时间校准”网关在转发设备数据时用网关自己的时间戳覆盖设备原始时间戳或者在设备端强制 NTP。数据源时间是统一的时序一致性才有意义。4.3 从 MySQL 表结构自动转向 TDengine 的思路热词里有一条“mysql表结构自动转tdengine超级表子表”这需求太真实了我自己也做过类似工具。迁移的核心不是逐表复制而是理解字段映射关系。MySQL 的字段类型和 TDengine 的字段类型需要做一套映射一般是这样INT/BIGINT - INT/BIGINTFLOAT/DOUBLE - FLOAT/DOUBLEDATETIME/TIMESTAMP - TIMESTAMPVARCHAR - BINARY 或 NCHAR注意 TDengine 里 BINARY 是单字节存储NCHAR 支持多字节字符中文最好用 NCHARTEXT - BINARY/NCHAR 够长即可但 TDengine 不适合存大文本具体到代码我写过一段简单的 Python 脚本从 MySQL information_schema 读取列定义再生成 TDengine 的建超级表语句。核心逻辑大致是import pymysql conn pymysql.connect(hostlocalhost, userroot, passwordxxx, databasemydb) cur conn.cursor() cur.execute(SELECT column_name, data_type, column_comment FROM information_schema.columns WHERE table_schemamydb AND table_namedevice_real) cols [] for col_name, col_type, comment in cur.fetchall(): if col_type in (int, bigint): cols.append(f{col_name} INT) elif col_type in (float, double): cols.append(f{col_name} FLOAT) elif col_type in (datetime, timestamp): cols.append(f{col_name} TIMESTAMP) elif col_type in (varchar, text, char): cols.append(f{col_name} NCHAR(200)) else: cols.append(f{col_name} NCHAR(100)) print(CREATE STABLE device_real (ts TIMESTAMP, , .join(cols) ) TAGS(device_id NCHAR(32), group_id INT);)注意脚本输出的结果通常还要人工微调尤其是把哪个字段设为时间戳、哪个字段拆分到标签。拆分到这里之后再写一条迁移程序把 MySQL 数据按照主键时间顺序批量导入 TDengine就完成了第一步的平滑过渡。TDengine 没有 MySQL 那样丰富的索引体系设计的关键还是“时间戳标签”的结构。5. 写入、读取与编程绑定实操层面这几件事最重要5.1 刚写入的数据马上读不到是怎么回事“tdengine 保存临时数据马上读取”这个问题我同事踩过很多次。现象是 insert 语句返回成功但立刻 select 查不到数据。先说结论TDengine 正常情况下写入成功后立即可查因为数据会先进入内存 vnode 和 WAL查询路径并不依赖落盘。那为什么查不到最常见的原因是用了不同的数据库、不同的时区或者 REST 接口和原生接口的时区不一致。比如你用 taos 命令行插入的是本地时间然后用 REST API 查REST 默认按 UTC 处理时间窗口对不上就会查不到。解决方法是连接时指定时区TDengine 在 JDBC 驱动的连接串里、REST API 的参数里都能设置 timezone。第二个常见原因是我上面提到的时间戳重复。TDengine 对主键有唯一性约束同一条子表里时间戳相同会视为重复数据哪怕值不同默认行为也可能是丢弃或者返回成功实际没有覆盖。所以插入数据时一定要确保时间戳唯一测试环境可以简化生产环境必须带毫秒甚至微秒精度。还有个容易忽略的问题如果你先创建了超级表再用 INSERT VALUES 插入多行但写错了数据库名或表名前缀SQL 执行成功但行数增量为 0也会产生“找不到数据”的错觉。建议在写入后马上 check 一下 affected rows用select count(*) from meters来验证。5.2 C 绑定写入数据库与 taos_stmt_prepareC 项目对接 TDengine 是 IoT 场景里的高频需求。TDengine 3.x 的 C/C 接口使用 libtaos 动态库官方在镜像和安装包里都内置了客户端库。如果你的业务容器需要访问 TDengine最简单的做法是在 Dockerfile 里安装 tdengine 客户端或者直接把宿主机上的 libtaos.so 挂载进去。但我在实际项目里和很多人强烈推荐的是不要直接用字符串拼 SQL 写入一定要用taos_stmt_prepare这一类预处理接口。原因很简单第一防止 SQL 注入风险——虽然时序数据大多是机器采集但参数一旦带外部输入就有风险第二性能更高——prepare 之后可以重复 bind 参数并执行避免了反复解析 SQL 的开销第三代码可读性好批量写入时逻辑更清晰。一个典型的 C 预处理写入流程是这样#include taos.h #include iostream int main() { TAOS* taos taos_connect(localhost, root, taosdata, testdb, 6030); if (!taos) return -1; TAOS_STMT* stmt taos_stmt_init(taos); const char* sql INSERT INTO ? USING meters TAGS(?,?) VALUES (?,?,?); taos_stmt_prepare(stmt, sql, 0); // 绑定表名、标签、数据列 taos_bind_vars_t bind_vars[6]; // 这里依次绑定 d001、Beijing、1、时间戳、电流、电压 taos_stmt_bind_param(stmt, bind_vars); taos_stmt_execute(stmt); taos_stmt_close(stmt); taos_close(taos); return 0; }上面的代码只是示意实际使用时需要仔细处理 TAOS_BIND 结构体里的 buffer_type 和 buffer_length。我的经验是先把一个子表的插入流程跑通再抽象成函数循环绑定多个设备。批量写入时建议在事务内执行多条 stmt能显著降低网络开销。另外再说一个小细节TDengine 的 taos CLI 和 C API 是不同的连接路径前者走 6030后者也可以通过 taosAdapter 走 6041。如果你在 Docker 网络里访问连接地址要用容器名或服务名不要用 localhost。这一点在做容器化部署时尤其容易踩。5.3 在 SpringBoot 应用里集成 TDengineJava 后端接入 TDengine 就绕不开 taos-jdbcdriver它支持 JDBC 原生连接和 REST 连接。如果你用的是若依RuoYi这类 SpringBoot 框架最省事的做法是在 pom.xml 中引入 JDBC 驱动然后在 application.yml 配置一个独立的数据源spring: datasource: tdengine: url: jdbc:TAOS-REST://localhost:6041/testdb driver-class-name: com.taosdata.jdbc.restful.TAOSRestfulDriver username: root password: taosdata这里我刻意使用 REST 驱动它不依赖 C 客户端库在容器化环境里更省心。代价是 REST 驱动的单次写入吞吐比原生连接低一些但中小规模场景完全够用。集成之后最重要的是别把 TDengine 的数据源交给 MyBatis/JPA 去自动建表时序数据库的表结构和关系型模型差别太大最好直接用 JdbcTemplate 或 MyBatis 手写 SQL 操作。6. 常见问题与排查技巧实录6.1 Docker Desktop 的虚拟化报错怎么处理我在第 2 章开头讲了virtualization support wasnt detected的基本解法。这里补充一个实战细节有些 Windows 机器打开 Hyper-V 后如果还在用旧版 WSL1Docker Desktop 照样会报这个错。要在 PowerShell 管理员模式下执行wsl --set-default-version 2如果执行后提示需要安装 WSL2 内核就去微软官网安装更新包。装完之后重启 Docker Desktop再看是否还报错。另外某些品牌机的 BIOS 默认把虚拟化开关藏在“Intel Virtualization Technology”和“VT-d”两个选项里只开前者也可能导致 Docker 无法使用嵌套虚拟化。这个错误本身不影响数据但会卡住整个部署流程值得优先处理。6.2 容器网络不通的排查思路“docker 网络不通”这个热词在 TDengine 容器场景里的典型表现是业务容器在本地 docker 网络中连接不了 TDengine 容器的 6030 端口。排查时我一般按三步走。第一步确认两个容器是否在同一个自定义网络中。直接用 docker run 默认 bridge 网络时容器虽然能互相 ping 通 IP但 IP 会随容器重启变化。最好在 docker compose 里让业务服务和 TDengine 处在同一个 service 网络这样可以用服务名tdengine作为 hostname 访问。第二步在业务容器里用telnet tdengine 6030或nc -zv tdengine 6030测试端口。如果端口不通检查 TDengine 容器是否暴露了端口。docker compose 里的 ports 映射是宿主机端口映射不自动影响容器间访问容器间访问必须确认服务监听地址不是 127.0.0.1。TDengine 默认监听 0.0.0.0一般没问题。第三步查看 TDengine 的日志。docker compose logs tdengine里出现Unable to resolve host或connection refused时大概率是 FQDN 配置问题。TDengine 3.x 在分布式环境下对 hostname 特别敏感单机容器里也最好指定hostname: tdengine并保持一致。6.3 卷权限、镜像下载与端口占用卷权限是另一个高频问题。docker compose 挂载宿主机目录后容器内进程如果以非 root 用户运行可能没有挂载目录的写权限典型报错是/var/lib/taos: permission denied。我的习惯是先把目录权限放宽到当前用户或者干脆在 compose 配置里给 taosd 设置 user 字段user: 1000:1000保证宿主机目录和容器内用户 ID 一致。镜像下载慢的问题前面已经讲了 registry mirror 的方案这里不再赘述。端口占用则是另一个隐藏的大坑如果你之前在本机装过原生 TDengine它可能已经占用了 6030这时候 docker compose 会报port is already allocated。出现这种情况要么停掉原生服务要么把宿主机端口改成 6031 之类的非标端口ports: - 6031:6030这样容器内部仍监听 6030但宿主机对外暴露 6031客户端连接时用 6031 即可。6.4 表注释、字段类型映射的其他坑热词里有一条“字段注释comment”这也是 MySQL 迁移者最容易问的。TDengine 3.x 对 CREATE TABLE 的字段注释支持并不像 MySQL 那样宽松如果你从 MySQL 拷来的 DDL 里带了一堆 COMMENT直接执行很可能会报语法错误。我的方案是建表阶段统一去掉 COMMENT维护一份单独的字段说明文档或者用 TDengine 自身支持的表注释特性。如果你确实需要保留注释建议先在目标版本上验证语法再批量执行别指望全套兼容。字段类型映射方面MySQL 的 VARCHAR 在 TDengine 里建议用 NCHAR因为 BINARY 是字节存储遇到中文会乱码或者截断。但 NCHAR 的长度单位是字符不要按字节去算。老项目里如果已经用了 BINARY 并且出现中文乱码问题需要重建表才能彻底解决这是一个典型的“开头省事、后期费事”的典型所以建议从一开始就明确字符集和字段类型规则。最后再分享一个小经验TDengine 镜像升级时不要直接替换 tag 后启动最好先把数据卷备份一份再在测试环境验证新版本的兼容性。我从 3.0 升到 3.2 的过程中遇到过默认配置变化导致 taosAdapter 端口不一致的情况提前备份和验证能避免线上事故。docker 安装管理 TDengine 这套流程只要把环境、镜像、建模、写入这四层想清楚后面基本就是按部就班的事。
我第一次把 TDengine 和 Docker 放在一起折腾是在一个物联网网关项目里。当时赶上设备数据量暴涨MySQL 的存储和聚合都开始吃力团队临时决定引入时序数据库做试点。网上一搜TDengine 的 docker 安装命令确实看起来简单拉一个镜像、跑一个容器、进去建表三分钟就能用上。但真正跑到业务里才发现docker 安装管理 TDengine 这件事远不止“容器起来了”这么简单多表时序一致性怎么保证、子表和超级表怎么设计、C 程序对接时该不该用 taos_stmt_prepare、甚至刚插入的数据为什么有时候查不到——这些问题每一个都能让人卡上一整天。这篇文章我会从零开始把“docker 安装管理 TDengine”这个主题拆透了来讲。内容覆盖 Docker 环境准备、镜像选型、docker-compose 生产级配置、TDengine 的超级表/子表建模、多表时序一致的实践思路以及 C 绑定写入和常见问题排查。适合物联网开发、后端开发、数据平台运维还有那些正打算把业务从 MySQL 迁到时序数据库的同学。你不需要有多高深的 Docker 基础跟着步骤走就能把一套可用的 TDengine 跑起来同时避开我踩过的那些坑。1. 项目拆解为什么我坚持用 Docker 部署 TDengine1.1 先搞清楚 TDengine 到底是干什么的TDengine 的全称是 Time Series Database直译就是“时序数据库”但它和传统的关系型数据库思路完全不一样。普通数据库把数据看作一张张彼此独立的表而 TDengine 天生服务的是“测点”和“时间线”这类场景一台风机每秒上报一次转速、一组电表每 5 分钟采集一次电压、一辆车每隔 100 毫秒上报一次 GPS 坐标。这类数据的共同特征是写入极频繁、数据量大、时间维度强相关、很少更新删除而且绝大部分查询都是“按时间范围做聚合统计”。你可以把 TDengine 想象成一本严格按时间排序的账本每一行记录都带着时间戳和若干测量值再挂上一组设备维度的标签。在这本账本里建表不是为“某个实体”建而是为“某条测点流”建。这样设计最大的好处是同一批设备的多个测点会天然落在相同的时间结构里查询窗口聚合、降采样、插值都能在数据库内部完成不用像 MySQL 那样靠 group by 硬撑。理解这一点后面对超级表、子表的理解就不会跑偏。1.2 Docker 部署的收益和适用场景官方其实提供了 rpm、deb、源码编译等方式安装 TDengine生产环境里也有不少人直接在物理机或云主机上装原生服务。但我个人在大多数项目中还是默认走 Docker原因很直接依赖隔离。TDengine 的安装过程不是简单的“装完就能用”它涉及服务端 taosd、客户端 taos、配置文件 taos.cfg、数据目录、日志目录、甚至 3.x 版本新增的 taosAdapter 组件。用 Docker 装这些组件全部打进镜像里宿主机上只需要有 Docker 引擎和一块能够持久化数据的磁盘几乎不用关心系统是 CentOS 7 还是 Ubuntu 22.04。Docker 部署还有一个非常实用的价值是“环境可复现”。我在本地用 docker run 调好的参数写进 docker-compose.yml提交到仓库之后同事拉下来 docker compose up -d 就能得到完全一致的环境。这一点对团队协作和测试环境搭建特别重要。当然Docker 也不是万能的。如果你要搭建一个超过 3 节点的高可用 TDengine 集群且对网络延迟和磁盘 IO 有苛刻要求那我还是建议直接用裸机或者 Kubernetes 管理有状态服务Docker 单机模式只适合开发、测试以及中小规模生产。我在下文给的方案就是围绕单机版 docker compose 展开的。2. 环境准备Docker 安装与启动避坑2.1 Docker Desktop 启动失败的几种常见情况很多人第一步就挂在 Docker Desktop 启动上尤其是 Windows 用户。最常见的报错是Docker Desktop failed to start because virtualization support wasnt detected这个报错的原意是 Docker Desktop 依赖虚拟化能力来运行 Linux 容器但系统层面没检测到。我在 Windows 上遇到过三次基本可以按下面顺序排查。第一确认 BIOS/UEFI 里的虚拟化开关已经打开。不同主板名字不一样常见的有 Intel VT-x、AMD-V、SVM Mode一般都在 CPU Configuration 或者 Advanced 菜单里。改完设置要完全断电重启不能只做系统重启。第二Windows 的虚拟机平台和 Hyper-V 功能需要开启。控制面板 - 程序和功能 - 启用或关闭 Windows 功能把 Hyper-V、适用于 Linux 的 Windows 子系统、虚拟机平台 这三项都勾上。第三WSL2 内核需要更新。微软官网有独立的 WSL2 Linux 内核更新包下载安装后重启Docker Desktop 基本就能正常启动了。Linux 桌面环境下还有另一种常见情况Docker 安装成功但普通用户无法执行 docker 命令报错提示 /var/run/docker.sock 权限不足。解决办法是把当前用户加入 docker 用户组sudo usermod -aG docker $USER newgrp docker需要注意的是加入 docker 组等同于给用户 root 级别的容器管理权限这只适合开发机生产服务器上要谨慎。2.2 镜像加速与网络初始化镜像拉不下来、拉得慢是国内使用 Docker 最常见的痛。为解决这个问题Docker 提供了镜像加速配置修改 Docker 引擎的 daemon.json。在 Linux 上路径是 /etc/docker/daemon.json在 Docker Desktop 上可以在 Settings - Docker Engine 里直接编辑。我一般会在这类配置文件里放一个或两个可靠的 registry mirror 地址{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com ] }改完执行systemctl restart dockerLinux或点击 Docker Desktop 的 Apply Restart。这一步不解决所有网络问题但能明显提升 TDengine 这类常用镜像的拉取速度。另外Docker 默认创建的是 bridge 网络容器内容器之间默认可以互联但如果宿主机防火墙策略很严容器访问宿主机或者外部访问容器端口也可能被拦后面第 6 章我会专门讲网络排查。2.3 Docker Compose 的准备Docker Compose 在 Docker Desktop 里默认集成Linux 下则需要单独确认。现在 Docker 官方推荐的是 compose 插件模式命令是docker compose version。如果你的系统里没有可以通过系统包管理器安装sudo apt-get install docker-compose-plugin或者直接按 Docker 官方文档安装 compose v2 插件。我强烈建议用 v2 而不是老的 python 版 docker-compose因为 v2 的配置文件格式和命令行参数更加一致docker compose up -d这种操作在团队内部更好统一。确认好 compose 可用以后就可以进入 TDengine 的实际部署了。3. docker 安装 TDengine从快速验证到生产配置3.1 镜像版本怎么选TDengine 官方镜像名是 tdengine/tdengine。选版本是第一个大坑2.x 和 3.x 的差异非常大2.6 的很多命令和表结构到了 3.x 都不再兼容尤其是超级表的创建语法、客户端连接方式、还有 taosAdapter 的组件化设计。如果你的项目是从零起步直接选 3.x 最新稳定版例如 3.3.x如果是要接手老项目则必须确认原来业务基于哪个大版本不能盲目拉到 latest。另一个容易踩的坑是镜像 tag 的准确写法。latest 虽然方便但无法复现环境。我会在 docker-compose.yml 里固定具体版本号例如tdengine/tdengine:3.3.0.10并把镜像 tag 单独写成一个变量方便后续升级。这样做的好处是线上环境出问题时你能确定容器跑的到底是哪个版本排查日志不至于对着不同版本的 SQL 语法发懵。3.2 一条 docker run 命令做冒烟测试如果是想先快速体验一下不涉及持久化和多容器编排直接用 docker run 完全够用。TDengine 3.x 最需要关心的端口有四个端口用途6030TDengine 原生客户端连接端口taos 命令行、C/C 客户端、JDBC 原生连接6041REST 接口端口HTTP 客户端和很多语言 SDK 默认走这个6043taosAdapter 提供的扩展服务端口6045taosX/Explorer 等 Web 工具端口我一般做冒烟测试会这样跑docker run -d \ --name tdengine \ -p 6030:6030 \ -p 6041:6041 \ -p 6043:6043 \ -p 6045:6045 \ tdengine/tdengine:3.3.0.10启动之后进容器里验证 taos 命令行是否能正常连接docker exec -it tdengine taos看到 taos 的命令行提示符以后先建一个测试数据库和一张最简单的表CREATE DATABASE testdb; USE testdb; CREATE TABLE sensor (ts TIMESTAMP, temperature FLOAT); INSERT INTO sensor VALUES (2025-05-01 10:00:00.000, 36.5); SELECT * FROM sensor;如果这条链路走通说明容器基本正常端口映射也没有问题。冒烟测试用不着的端口可以不开毕竟每个端口都意味着一个暴露面但 6030 和 6041 建议保留。3.3 生产级 docker-compose 配置与数据持久化线上使用就不能只靠 docker run 了我推荐把配置沉淀成 docker-compose.yml。这里有一份我实际在用的模板覆盖了数据卷、日志、时区、重启策略和健康检查version: 3.8 services: tdengine: image: tdengine/tdengine:3.3.0.10 container_name: tdengine hostname: tdengine restart: always environment: - TZAsia/Shanghai ports: - 6030:6030 - 6041:6041 - 6043:6043 - 6045:6045 volumes: - ./tdengine/data:/var/lib/taos - ./tdengine/log:/var/log/taos command: - taosd healthcheck: test: [CMD-SHELL, taos -c /etc/taos/taos.cfg -s show databases || exit 1] interval: 30s timeout: 10s retries: 3 start_period: 30s这里要特别说明持久化。TDengine 的官方镜像把数据放在容器内部的 /var/lib/taos日志放在 /var/log/taos。如果不做卷映射容器一销毁数据全部消失。我把宿主机上的 ./tdengine/data 和 ./tdengine/log 挂载进容器升级镜像、重建容器都不会丢数据。第一次启动之前我还会确认宿主机的挂载目录存在且有权限否则会覆盖成 root 目录进而出现写入问题。本地验证时用docker compose up -d启动用docker compose logs -f tdengine看日志看到类似Vnode is created或者service is ready的日志说明服务启动完成。生产环境里我还习惯给容器加一个 healthcheck方便编排平台感知服务状态。4. 库表设计超级表、子表与多表时序一致4.1 超级表和子表到底怎么建TDengine 里最重要也最容易搞混的概念是超级表STABLE。通俗地说超级表是“模板”子表是“实例”。超级表定义了所有子表共有的数据列和标签列标签列通常用来描述设备属性比如地点、分组、设备型号数据列则是随时间变化的测量值。举个例子我们有 100 台电表每台电表都要记录电流和电压。如果用 MySQL 思路可能会建 100 张表或者一张大表里加设备字段。TDengine 的正确姿势是先建一张超级表再按设备建子表CREATE STABLE meters ( ts TIMESTAMP, current FLOAT, voltage INT ) TAGS ( location BINARY(32), group_id INT );注意这里的 TAGS 和表的字段是分开的。标签列不是普通数据列它用来描述子表的维度属性。然后插入数据时会自动创建子表INSERT INTO d001 USING meters TAGS(Beijing, 1) VALUES (NOW, 12.4, 220); INSERT INTO d002 USING meters TAGS(Shanghai, 1) VALUES (NOW, 8.2, 220);执行之后TDengine 自动为你创建了 d001、d002 两张子表它们都继承了 meters 的列结构标签值分别为北京/上海。查询时你既可以查单张子表也可以直接查超级表后面这种操作可以跨所有设备取数。我在设计表结构时的一个习惯是把不经常变化的设备属性全部放在标签列把随时间变化的物理量放在数据列这能让后续聚合查询效率提升不少。4.2 “多个表时序一致”的落地做法“tdengine 如何做到多个表时序一致”这个热搜词我一直觉得很典型。刚开始接触 TDengine 的同事总会担心不同子表之间的时间戳对不上比如设备 A 的读数在 10:00:00.100设备 B 的读数在 10:00:01.200那窗口聚合时是不是就乱了其实时序一致的基本盘是“以采集时间为主键而不是以入库时间为主键”。TDengine 的数据模型中TIMESTAMP 列就是主键它必须是严格唯一的。只要你在写入时传的是设备真实采集时间戳而不是依赖数据库的当前时间那么不同子表之间的数据天然可以在时间轴上对齐。比如要统计每分钟的平均电流SQL 会写成SELECT _wstart, AVG(current) FROM meters WHERE ts 2025-05-01 00:00:00 AND ts 2025-05-01 00:10:00 INTERVAL(1m);这个 INTERVAL 窗口聚合会把所有子表的数据按分钟切割同一分钟内的电流全部参与平均不会出现 A 表和 B 表时间错位的问题。不过多表真正容易出问题的地方不是查询而是写入端的时间一致性。如果设备时间没有做 NTP 同步每台设备都会按自己的时钟上报即便查询语法是时序对齐的数据本身就错位了。所以我在实际项目中会额外做一层“时间校准”网关在转发设备数据时用网关自己的时间戳覆盖设备原始时间戳或者在设备端强制 NTP。数据源时间是统一的时序一致性才有意义。4.3 从 MySQL 表结构自动转向 TDengine 的思路热词里有一条“mysql表结构自动转tdengine超级表子表”这需求太真实了我自己也做过类似工具。迁移的核心不是逐表复制而是理解字段映射关系。MySQL 的字段类型和 TDengine 的字段类型需要做一套映射一般是这样INT/BIGINT - INT/BIGINTFLOAT/DOUBLE - FLOAT/DOUBLEDATETIME/TIMESTAMP - TIMESTAMPVARCHAR - BINARY 或 NCHAR注意 TDengine 里 BINARY 是单字节存储NCHAR 支持多字节字符中文最好用 NCHARTEXT - BINARY/NCHAR 够长即可但 TDengine 不适合存大文本具体到代码我写过一段简单的 Python 脚本从 MySQL information_schema 读取列定义再生成 TDengine 的建超级表语句。核心逻辑大致是import pymysql conn pymysql.connect(hostlocalhost, userroot, passwordxxx, databasemydb) cur conn.cursor() cur.execute(SELECT column_name, data_type, column_comment FROM information_schema.columns WHERE table_schemamydb AND table_namedevice_real) cols [] for col_name, col_type, comment in cur.fetchall(): if col_type in (int, bigint): cols.append(f{col_name} INT) elif col_type in (float, double): cols.append(f{col_name} FLOAT) elif col_type in (datetime, timestamp): cols.append(f{col_name} TIMESTAMP) elif col_type in (varchar, text, char): cols.append(f{col_name} NCHAR(200)) else: cols.append(f{col_name} NCHAR(100)) print(CREATE STABLE device_real (ts TIMESTAMP, , .join(cols) ) TAGS(device_id NCHAR(32), group_id INT);)注意脚本输出的结果通常还要人工微调尤其是把哪个字段设为时间戳、哪个字段拆分到标签。拆分到这里之后再写一条迁移程序把 MySQL 数据按照主键时间顺序批量导入 TDengine就完成了第一步的平滑过渡。TDengine 没有 MySQL 那样丰富的索引体系设计的关键还是“时间戳标签”的结构。5. 写入、读取与编程绑定实操层面这几件事最重要5.1 刚写入的数据马上读不到是怎么回事“tdengine 保存临时数据马上读取”这个问题我同事踩过很多次。现象是 insert 语句返回成功但立刻 select 查不到数据。先说结论TDengine 正常情况下写入成功后立即可查因为数据会先进入内存 vnode 和 WAL查询路径并不依赖落盘。那为什么查不到最常见的原因是用了不同的数据库、不同的时区或者 REST 接口和原生接口的时区不一致。比如你用 taos 命令行插入的是本地时间然后用 REST API 查REST 默认按 UTC 处理时间窗口对不上就会查不到。解决方法是连接时指定时区TDengine 在 JDBC 驱动的连接串里、REST API 的参数里都能设置 timezone。第二个常见原因是我上面提到的时间戳重复。TDengine 对主键有唯一性约束同一条子表里时间戳相同会视为重复数据哪怕值不同默认行为也可能是丢弃或者返回成功实际没有覆盖。所以插入数据时一定要确保时间戳唯一测试环境可以简化生产环境必须带毫秒甚至微秒精度。还有个容易忽略的问题如果你先创建了超级表再用 INSERT VALUES 插入多行但写错了数据库名或表名前缀SQL 执行成功但行数增量为 0也会产生“找不到数据”的错觉。建议在写入后马上 check 一下 affected rows用select count(*) from meters来验证。5.2 C 绑定写入数据库与 taos_stmt_prepareC 项目对接 TDengine 是 IoT 场景里的高频需求。TDengine 3.x 的 C/C 接口使用 libtaos 动态库官方在镜像和安装包里都内置了客户端库。如果你的业务容器需要访问 TDengine最简单的做法是在 Dockerfile 里安装 tdengine 客户端或者直接把宿主机上的 libtaos.so 挂载进去。但我在实际项目里和很多人强烈推荐的是不要直接用字符串拼 SQL 写入一定要用taos_stmt_prepare这一类预处理接口。原因很简单第一防止 SQL 注入风险——虽然时序数据大多是机器采集但参数一旦带外部输入就有风险第二性能更高——prepare 之后可以重复 bind 参数并执行避免了反复解析 SQL 的开销第三代码可读性好批量写入时逻辑更清晰。一个典型的 C 预处理写入流程是这样#include taos.h #include iostream int main() { TAOS* taos taos_connect(localhost, root, taosdata, testdb, 6030); if (!taos) return -1; TAOS_STMT* stmt taos_stmt_init(taos); const char* sql INSERT INTO ? USING meters TAGS(?,?) VALUES (?,?,?); taos_stmt_prepare(stmt, sql, 0); // 绑定表名、标签、数据列 taos_bind_vars_t bind_vars[6]; // 这里依次绑定 d001、Beijing、1、时间戳、电流、电压 taos_stmt_bind_param(stmt, bind_vars); taos_stmt_execute(stmt); taos_stmt_close(stmt); taos_close(taos); return 0; }上面的代码只是示意实际使用时需要仔细处理 TAOS_BIND 结构体里的 buffer_type 和 buffer_length。我的经验是先把一个子表的插入流程跑通再抽象成函数循环绑定多个设备。批量写入时建议在事务内执行多条 stmt能显著降低网络开销。另外再说一个小细节TDengine 的 taos CLI 和 C API 是不同的连接路径前者走 6030后者也可以通过 taosAdapter 走 6041。如果你在 Docker 网络里访问连接地址要用容器名或服务名不要用 localhost。这一点在做容器化部署时尤其容易踩。5.3 在 SpringBoot 应用里集成 TDengineJava 后端接入 TDengine 就绕不开 taos-jdbcdriver它支持 JDBC 原生连接和 REST 连接。如果你用的是若依RuoYi这类 SpringBoot 框架最省事的做法是在 pom.xml 中引入 JDBC 驱动然后在 application.yml 配置一个独立的数据源spring: datasource: tdengine: url: jdbc:TAOS-REST://localhost:6041/testdb driver-class-name: com.taosdata.jdbc.restful.TAOSRestfulDriver username: root password: taosdata这里我刻意使用 REST 驱动它不依赖 C 客户端库在容器化环境里更省心。代价是 REST 驱动的单次写入吞吐比原生连接低一些但中小规模场景完全够用。集成之后最重要的是别把 TDengine 的数据源交给 MyBatis/JPA 去自动建表时序数据库的表结构和关系型模型差别太大最好直接用 JdbcTemplate 或 MyBatis 手写 SQL 操作。6. 常见问题与排查技巧实录6.1 Docker Desktop 的虚拟化报错怎么处理我在第 2 章开头讲了virtualization support wasnt detected的基本解法。这里补充一个实战细节有些 Windows 机器打开 Hyper-V 后如果还在用旧版 WSL1Docker Desktop 照样会报这个错。要在 PowerShell 管理员模式下执行wsl --set-default-version 2如果执行后提示需要安装 WSL2 内核就去微软官网安装更新包。装完之后重启 Docker Desktop再看是否还报错。另外某些品牌机的 BIOS 默认把虚拟化开关藏在“Intel Virtualization Technology”和“VT-d”两个选项里只开前者也可能导致 Docker 无法使用嵌套虚拟化。这个错误本身不影响数据但会卡住整个部署流程值得优先处理。6.2 容器网络不通的排查思路“docker 网络不通”这个热词在 TDengine 容器场景里的典型表现是业务容器在本地 docker 网络中连接不了 TDengine 容器的 6030 端口。排查时我一般按三步走。第一步确认两个容器是否在同一个自定义网络中。直接用 docker run 默认 bridge 网络时容器虽然能互相 ping 通 IP但 IP 会随容器重启变化。最好在 docker compose 里让业务服务和 TDengine 处在同一个 service 网络这样可以用服务名tdengine作为 hostname 访问。第二步在业务容器里用telnet tdengine 6030或nc -zv tdengine 6030测试端口。如果端口不通检查 TDengine 容器是否暴露了端口。docker compose 里的 ports 映射是宿主机端口映射不自动影响容器间访问容器间访问必须确认服务监听地址不是 127.0.0.1。TDengine 默认监听 0.0.0.0一般没问题。第三步查看 TDengine 的日志。docker compose logs tdengine里出现Unable to resolve host或connection refused时大概率是 FQDN 配置问题。TDengine 3.x 在分布式环境下对 hostname 特别敏感单机容器里也最好指定hostname: tdengine并保持一致。6.3 卷权限、镜像下载与端口占用卷权限是另一个高频问题。docker compose 挂载宿主机目录后容器内进程如果以非 root 用户运行可能没有挂载目录的写权限典型报错是/var/lib/taos: permission denied。我的习惯是先把目录权限放宽到当前用户或者干脆在 compose 配置里给 taosd 设置 user 字段user: 1000:1000保证宿主机目录和容器内用户 ID 一致。镜像下载慢的问题前面已经讲了 registry mirror 的方案这里不再赘述。端口占用则是另一个隐藏的大坑如果你之前在本机装过原生 TDengine它可能已经占用了 6030这时候 docker compose 会报port is already allocated。出现这种情况要么停掉原生服务要么把宿主机端口改成 6031 之类的非标端口ports: - 6031:6030这样容器内部仍监听 6030但宿主机对外暴露 6031客户端连接时用 6031 即可。6.4 表注释、字段类型映射的其他坑热词里有一条“字段注释comment”这也是 MySQL 迁移者最容易问的。TDengine 3.x 对 CREATE TABLE 的字段注释支持并不像 MySQL 那样宽松如果你从 MySQL 拷来的 DDL 里带了一堆 COMMENT直接执行很可能会报语法错误。我的方案是建表阶段统一去掉 COMMENT维护一份单独的字段说明文档或者用 TDengine 自身支持的表注释特性。如果你确实需要保留注释建议先在目标版本上验证语法再批量执行别指望全套兼容。字段类型映射方面MySQL 的 VARCHAR 在 TDengine 里建议用 NCHAR因为 BINARY 是字节存储遇到中文会乱码或者截断。但 NCHAR 的长度单位是字符不要按字节去算。老项目里如果已经用了 BINARY 并且出现中文乱码问题需要重建表才能彻底解决这是一个典型的“开头省事、后期费事”的典型所以建议从一开始就明确字符集和字段类型规则。最后再分享一个小经验TDengine 镜像升级时不要直接替换 tag 后启动最好先把数据卷备份一份再在测试环境验证新版本的兼容性。我从 3.0 升到 3.2 的过程中遇到过默认配置变化导致 taosAdapter 端口不一致的情况提前备份和验证能避免线上事故。docker 安装管理 TDengine 这套流程只要把环境、镜像、建模、写入这四层想清楚后面基本就是按部就班的事。
