TDengine Docker 部署实战镜像启动、环境变量、健康检查与 Docker Compose 集群搭建【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengineTDengine 官方镜像tdengine/tsdb-ee默认激活 HTTP 服务一条docker run命令即可在容器中启动数据库并通过环境变量精细控制 fqdn、root 密码、端口与附加组件行为。本文以 docs/zh/12-operations-and-tooling/02-operations/03-deployment/02-docker.md 为主线结合镜像构建文件与入口脚本的源码实现系统讲解单节点启动、host 网络模式、自定义 hostname、Docker Compose 三节点集群搭建以及 root 密码升级与健康检查的版本差异帮助你快速获得可复制、可上生产的容器化 TDengine 部署方案。一、镜像基础从 Dockerfile 看镜像内含组件在进入部署操作前先通过镜像构建文件了解容器内默认启动的服务。从 packaging/docker/Dockerfile 可以看到镜像基于tdengine/tdengine-tsdb-base:1.0构建内部通过install.sh -e no免交互安装 TDengine并拷入taos*可执行文件、驱动与头文件声明了数据、日志卷VOLUME [/var/lib/taos, /var/log/taos]端口声明EXPOSE 6030 6041 6043 6060分别对应 taosd 原生端口6030、taosAdapter HTTP 端口6041、taosKeeper 监控端口6043、taosExplorer 图形化界面端口6060入口点为/usr/bin/tini -- /usr/bin/entrypoint.sh即容器以 tini 作为 init 进程再执行 entrypoint 脚本完成环境初始化与多进程拉起。容器默认不止启动 taosd根据 packaging/docker/bin/entrypoint.sh启动完成后还会依次拉起 taosadapter6041、taoskeeper6043、taos-explorer6060并各自等待对应端口的/metrics就绪。这也是下文“镜像默认激活 HTTP 服务”的根源。二、版本差异说明自定义密码、升级与健康检查使用 Docker 部署 TDengine 时root 密码、镜像升级与健康检查在不同版本阶段行为存在差异需先建立统一认知后续涉及密码、升级或taos-check的场景均以此为准3.3.6.6~3.3.8.4版本如果曾在旧版本中修改过 root 密码升级后需先在data目录默认/var/lib/taos下手动创建空标记文件.docker-entrypoint-root-password-changed再启动容器。该标记文件的作用可回溯到入口脚本entrypoint 只有在该文件不存在、且TAOS_ROOT_PASSWORD非默认值taosdata时才会执行taos -s ALTER USER root PASS 密码并 touch 该文件见 packaging/docker/bin/entrypoint.sh。也就是说标记文件是 entrypoint 判断“密码是否已按环境变量同步过”的依据。3.3.8.8及以上版本可通过TAOS_ROOT_PASSWORD或TAOS_ROOT_PASSWORD_FILE提供当前 root 密码镜像可直接升级但如果此前已修改过 root 密码在升级、重启容器或重建 Pod 之前仍需确保部署配置中提供的是当前实际密码否则入口脚本可能再次执行密码变更逻辑造成密码不一致。3.4.1.0及以上版本新增taos-check startup与taos-check service两个健康检查命令其中taos-check service会复用上述密码来源。如果密码未同步更新健康检查以及其他使用 root 账号鉴权的组件如 taosKeeper、taosAdapter 的监控上报可能失败。三、启动单节点 TDengine 并验证 HTTP 服务3.1 基本启动命令TDengine 镜像启动时默认激活 HTTP 服务执行如下命令即可创建一个带 HTTP 服务的容器化 TDengine 环境docker run -d --name tdengine \ -v ~/data/taos/dnode/data:/var/lib/taos \ -v ~/data/taos/dnode/log:/var/log/taos \ -p 6041:6041 tdengine/tsdb-ee参数说明/var/lib/taosTDengine 默认数据文件目录可通过配置文件dataDir修改位置/var/log/taosTDengine 默认日志文件目录可通过配置文件logDir修改位置-p 6041:6041将容器内 taosAdapter 的 HTTP 端口 6041 映射到主机同名端口。数据与日志目录通过 volume 挂载到宿主机是容器重建后数据不丢失的关键。3.2 验证 HTTP 服务容器启动后可通过 RESTful 接口验证 HTTP 服务是否可用默认账号root默认密码taosdatacurl -u root:taosdata -d show databases localhost:6041/rest/sql3.3 进入容器使用 taos shell运行如下命令可在容器中直接访问 TDengine$ docker exec -it tdengine taos taos show databases; name | information_schema | performance_schema | Query OK, 2 rows in database (0.033802s)需要特别说明连接方式在容器内部taosshell 以及各种连接器例如 JDBC-JNI与服务器通过容器的 hostname 建立连接。从容器外访问容器内的 TDengine 相对复杂通过 RESTful / WebSocket 连接方式是最简单的方法若业务需要原生协议直连请参考下文指定 hostname 或 host 网络模式。四、在 host 网络模式下启动 TDengine当希望直接使用主机的 FQDN 建立连接而非容器的 hostname时可使用 host 网络模式docker run -d --name tdengine --network host tdengine/tsdb-ee这种方式与在主机上使用 systemctl 启动 TDengine 的效果相同容器共享主机网络栈原生端口 6030 与 HTTP 端口 6041 直接暴露在主机上。若主机上已安装 TDengine 客户端可直接访问$ taos taos show dnodes; id | endpoint | vnodes | support_vnodes | status | create_time | note | 1 | vm98:6030 | 0 | 32 | ready | 2022-08-19 14:50:05.337 | | Query OK, 1 rows in database (0.010654s)五、以指定的 hostname 和 port 启动 TDengine对于需要外部客户端以原生协议6030直连、或在一台主机上部署多个实例的场景可通过TAOS_FQDN环境变量等价于 taos.cfg 中的fqdn配置项让 TDengine 在指定 hostname 上监听为部署提供更大灵活性。docker run -d \ --name tdengine \ -e TAOS_FQDNtdengine \ -p 6030:6030 \ -p 6041-6049:6041-6049 \ -p 6041-6049:6041-6049/udp \ tdengine/tsdb-ee上述命令做了三件事容器内 TDengine 监听的 hostname 为tdengine将容器端口 6030 映射到主机 6030原生通信端口将容器端口段[6041, 6049]TCP 与 UDP映射到主机相同端口段——TCP 用于 HTTP/WebSocket 及 RPCUDP 用于集群内节点心跳通信。若主机上该端口段已被占用可修改命令改指主机空闲端口段如果配置了rpcForceTcp 1强制走 TCP则可只映射 TCP 端口。其次确保tdengine这个 hostname 在/etc/hosts中可解析echo 127.0.0.1 tdengine |sudo tee -a /etc/hosts最后通过taosshell 以tdengine为服务器地址访问taos -h tdengine -P 6030如果TAOS_FQDN被设置为与所在主机名相同则效果等同于“在 host 网络模式下启动 TDengine”。注意v3.3.6.0之后默认fqdn从buildkitsandbox变更为localhost。全新启动没有问题若是升级启动运行容器时需要将-e TAOS_FQDN旧值与-h 旧值指定为之前的 fqdn否则可能无法启动。5.1 环境变量的实现原理TAOS_FQDN之所以能生效是因为入口脚本在启动 taosd 前会通过taosd -C读取当前生效配置并用正则解析出dataDir、fqdn、firstEp、serverPort等关键参数见 packaging/docker/bin/entrypoint.sh随后将解析出的 fqdn 追加写入容器/etc/hosts127.0.0.1 $FQDN保证自身可解析以该 fqdn 判断本节点是否为集群 firstEp从而决定是“作为首节点初始化”还是“等待首节点就绪后执行create dnode”加入集群。也就是说环境变量最终会落到 taos.cfg 对应的配置项上其行为与在 packaging/cfg/taos.cfg 中直接配置fqdn、firstEp、serverPort、dataDir、logDir完全一致。六、使用 Docker Compose 启动 3 节点集群6.1 编写 docker-compose.yaml使用如下 docker compose 配置文件可启动一个 3 节点 TDengine 集群services: td1: image: tdengine/tsdb-ee environment: - TAOS_FQDNtd1 td2: image: tdengine/tsdb-ee environment: - TAOS_FQDNtd2 - TAOS_FIRST_EPtd1:6030 td3: image: tdengine/tsdb-ee environment: - TAOS_FQDNtd3 - TAOS_FIRST_EPtd1:6030配置要点TAOS_FQDN为各节点指定独立 hostnametd1/td2/td3compose 网络内部会为服务名自动完成 DNS 解析TAOS_FIRST_EP用于指定集群中首个 dnode 的 endpoint效果与/etc/taos/taos.cfg中的firstEp参数一致是后续节点加入集群的“寻址入口”若集群使用了自定义 root 密码需在每个服务中同步配置对应的密码环境变量如TAOS_ROOT_PASSWORD并确保与数据库实际密码保持一致版本差异与升级要求仍以前文说明为准如需高可用可同时在配置中补充TAOS_SECOND_EP指向第二个可用节点生产环境建议为每个节点挂载独立的 named volume如taosdata-td1:/var/lib/taos、taoslog-td1:/var/log/taos完整示例可参考 packaging/docker/README.md 中的集群编排模板。6.2 启动集群并查看状态docker compose up启动后进入任一节点以 td1 为例docker compose exec td1 bash执行如下命令查看集群状态$ taos -s show dnodes Welcome to the TDengine Command Line Interface, Native Client Version:3.3.6.13 Copyright (c) 2025 by TDengine, all rights reserved. taos show dnodes id | endpoint | vnodes | support_vnodes | status | create_time | reboot_time | note | 1 | td1:6030 | 0 | 85 | ready | 2025-08-21 01:56:41.630 | 2025-08-21 01:56:41.465 | | 2 | td2:6030 | 1 | 85 | ready | 2025-08-21 01:56:43.203 | 2025-08-21 01:56:43.453 | | 3 | td3:6030 | 0 | 85 | ready | 2025-08-21 01:56:43.296 | 2025-08-21 01:56:43.491 | | Query OK, 3 row(s) in set (0.006355s)6.3 集群加入流程的源码视角从 packaging/docker/bin/entrypoint.sh 可以看清集群如何自组织若dataDir下已存在dnode/dnode.json已创建 dnode或dnode/mnodeEpSet.json已设置 mnode ep或本节点 fqdn 与 firstEp 主机名一致则直接以“已有 mnode ep”的方式启动 taosd否则该节点被判定为后续节点进入循环通过taos -h firstEp -P port --check轮询首节点就绪状态就绪后自动执行create dnode fqdn:serverPort完成入集群集群就绪后入口脚本还会在首节点执行初始化 SQL/docker-entrypoint-initdb.d/*.sql以.docker-entrypoint-inited标记只执行一次以及create snode on dnode 1创建流计算节点。理解这条链路有助于排查“节点迟迟不 ready”“容器反复重启”等集群启动问题。七、常见运维问题与排查指引容器反复重启优先检查 entrypoint 日志中taosd -C解析出的 fqdn/firstEp 是否符合预期重点确认升级场景下-e TAOS_FQDN是否沿用了旧值。健康检查失败3.4.1.0及以上版本使用taos-check startup/taos-check service若报鉴权错误请检查TAOS_ROOT_PASSWORD是否为数据库当前实际密码入口脚本的密码变更逻辑见 packaging/docker/bin/entrypoint.sh。外部客户端无法直连确认 fqdn 已在客户端/etc/hosts中解析、6030 端口已映射且未配置为默认localhost最简单的跨容器访问方式是走 6041 的 RESTful / WebSocket 接口。端口占用可调整-p映射到主机空闲端口段并同步修改客户端连接端口。八、延伸阅读手动部署systemctl / 裸机方式01-manual.mdKubernetes 部署与探针配置03-kubernetes.md镜像构建与更多编排模板taosAdapter 独立部署、Docker Swarm、客户端应用容器化packaging/docker/README.md容器内全部可配置项firstEp、secondEp、fqdn、serverPort、dataDir、logDir等packaging/cfg/taos.cfg【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
