TDengine Docker 部署完全指南环境变量、集群编排与健康检查实战【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine本文以 TDengine 官方 Docker 镜像tdengine/tsdb-ee为核心系统讲解如何通过docker run、host 网络模式、自定义 FQDN 以及 Docker Compose 三种方式部署单机与多节点 TDengine 集群并深入解析 root 密码定制、镜像升级与taos-check健康检查的版本差异。读完本文你将掌握容器内 TDengine 的完整生命周期管理从端口映射、数据卷挂载到集群自动组网并能根据镜像版本选择正确的密码与升级策略。本文对应的原始文档为 Docker 部署指南文中涉及的所有实现细节均可在本仓库 packaging/docker 目录下找到源码依据。镜像运行机制与关键目录TDengine 官方镜像在启动时会执行容器入口脚本见 packaging/docker/bin/entrypoint.sh该脚本完成三件核心工作读取环境变量所有以TAOS_前缀命名的环境变量会被转换为taos.cfg中对应的配置项如TAOS_FQDN对应fqdn、TAOS_FIRST_EP对应firstEp。解析并固化 FQDN脚本通过taosd -C读取当前 FQDN并自动将其写入容器内的/etc/hostsgrep $FQDN /etc/hosts /dev/null || echo 127.0.0.1 $FQDN /etc/hosts确保服务自身可以解析自己的主机名。按需拉起附属组件依次启动taosd、taosadapterREST 服务端口 6041、taoskeeper监控服务端口 6043与taos-explorer可视化界面端口 6060每个组件启动后都会通过各自的/metrics接口做就绪探测。镜像的默认目录约定见 packaging/docker/Dockerfile路径用途说明/var/lib/taos数据目录TDengine 默认数据文件存放目录可通过配置文件修改/var/log/taos日志目录默认日志文件存放目录可通过配置文件修改/etc/taos/taos.cfg配置文件镜像内置的默认配置文件/docker-entrypoint-initdb.d初始化 SQL 目录首次启动时按文件名顺序执行的*.sql脚本Dockerfile 通过VOLUME [/var/lib/taos, /var/log/taos]声明数据卷并通过ENTRYPOINT [/usr/bin/tini, --, /usr/bin/entrypoint.sh]使用 tini 作为 init 进程保证容器内多进程在收到停止信号时能被正确回收。镜像默认暴露的端口如下EXPOSE 6030 6041 6043 60606030taosd 原生连接端口TCP6041taosAdapter REST/WebSocket 端口6043taosKeeper 监控端口6060taosExplorer 界面端口自定义 root 密码、镜像升级与健康检查版本矩阵在使用自定义 root 密码时不同镜像版本的行为差异较大必须严格遵守以下版本规则本节规则同时适用于后文所有涉及密码、升级与taos-check的场景镜像版本密码处理方式注意事项3.3.6.6–3.3.8.4通过ALTER USER修改 root 密码若旧镜像中已修改过 root 密码再次启动容器前需在数据目录默认/var/lib/taos下创建空文件.docker-entrypoint-root-password-changed否则会重复执行改密逻辑导致启动异常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使用与 taosd 相同的密码来源因此过期的密码配置同样会导致健康检查失败并影响其他使用 root 账号认证的组件上述版本差异的根源可以从入口脚本中看到TAOS_ROOT_PASSWORD${TAOS_ROOT_PASSWORD:-taosdata}定义了默认密码只有在数据目录下不存在.docker-entrypoint-root-password-changed标记文件时脚本才会执行ALTER USER root PASS ...并创建该标记文件仅发生在集群首个节点。3.3.8.8之后改为要求显式提供当前密码3.4.1.0之后引入taos-check作为统一的健康检查入口。此外入口脚本还会将 root 密码同步给 taoskeeperexport TAOS_KEEPER_TDENGINE_PASSWORD${TAOS_ROOT_PASSWORD}确保监控组件与 taosd 使用一致的认证凭据。快速启动单机实例TDengine 镜像默认启用 HTTP 服务taosAdapter。执行以下命令创建一个带 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参数说明-v ~/data/taos/dnode/data:/var/lib/taos将宿主机的数据目录挂载到容器的/var/lib/taos保证容器重建后数据不丢失。-v ~/data/taos/dnode/log:/var/log/taos将日志目录挂载到宿主机便于统一收集与排查。-p 6041:6041将容器的 HTTP 服务端口 6041 映射到宿主机的 6041 端口。使用以下命令验证容器内的 HTTP 服务是否可用curl -u root:taosdata -d show databases localhost:6041/rest/sql使用以下命令进入容器访问 TDengine$ docker exec -it tdengine taos taos show databases; name | information_schema | performance_schema | Query OK, 2 rows in database (0.033802s)重要容器内的 TDengine 服务使用容器自身的 hostname 建立连接。因此从容器外部使用 TDengine CLI 或各类连接器如 JDBC-JNI访问容器内服务会比较复杂最简单的方式是使用 RESTful/WebSocket 连接对应 6041 端口。这一行为同样可以从入口脚本中看到——脚本会把容器 FQDN 写入/etc/hosts使 taosd 以容器 hostname 作为对外地址。使用 host 网络模式启动若希望使用宿主机的 FQDN 建立连接而非容器 hostname可切换到 host 网络模式docker run -d --name tdengine --network host tdengine/tsdb-ee该方式与在宿主机上通过systemctl启动 TDengine 的效果类似。如果宿主机已安装 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)host 网络模式下容器直接共享宿主机网络栈6030、6041等端口无需显式映射即可被宿主机上的客户端直接访问适合已有一套系统服务管理脚本systemd/sysvinit的运维环境迁移。指定主机名与端口启动利用TAOS_FQDN环境变量或taos.cfg中的fqdn配置项可以让 TDengine 在指定主机名下提供服务为部署提供更大的灵活性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启动 TDengine 服务将容器端口6030映射到宿主机6030将容器端口段[6041, 6049]同时以 TCP 和 UDP 协议映射到宿主机的[6041, 6049]。如果宿主机端口段已被占用可修改命令指定宿主机上的空闲端口段。TDengine 的集群内部通信RPC默认使用 UDP 与 TCP 双通道因此建议同时映射两种协议若已在配置中设置rpcForceTcp 1则只需映射 TCP。其次确保主机名tdengine可在/etc/hosts中解析将配置写入 hosts 文件echo 127.0.0.1 tdengine |sudo tee -a /etc/hosts最后使用 TDengine CLI 以tdengine作为服务器地址访问服务taos -h tdengine -P 6030如果TAOS_FQDN与宿主机 hostname 相同效果等同于host 网络模式启动。从源码看入口脚本 会根据taosd -C输出解析fqdn并写入/etc/hosts这保证了即便用户不显式设置 FQDN容器内的名称解析也是自洽的。版本提示v3.3.6.0 起v3.3.6.0之后默认fqdn由buildkitsandbox改为localhost。全新启动无影响但如果是从旧版本升级启动运行容器时必须用-e TAOS_FQDN旧值和-h 旧值指定此前的 fqdn否则可能启动失败。涉及 root 密码修改、镜像升级或taos-check行为时遵循前文版本矩阵中的规则。使用 Docker Compose 搭建 3 节点集群以下docker-compose.yaml可以拉起一个 3 节点的 TDengine TSDB 集群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为每个节点指定独立的 FQDNtd1/td2/td3Compose 内置 DNS 会自动将这些名称解析到对应容器。TAOS_FIRST_EP指定集群中要连接的首个 dnode 端点等价于/etc/taos/taos.cfg中的firstEp参数对应配置文件模板见 packaging/cfg/taos.cfg 中# firstEp hostname:6030条目。只有td1不设置该参数作为集群的第一个节点td2、td3通过它加入集群。自定义密码如果集群使用自定义 root 密码需要在每个 service 定义中加入对应的密码环境变量并保证与实际数据库密码保持一致升级与兼容性行为遵循前文版本矩阵。启动集群docker compose up集群启动后进入任意节点例如 td1docker 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.462 | | 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)当三个节点的状态均为ready时集群组网成功。集群自动组网原理从 入口脚本 可以完整还原集群的自动组网流程脚本通过taosd -C解析出dataDir、fqdn、firstEp、serverPort等配置首个节点td1FQDN 等于FIRST_EP_HOST直接启动taosd并等待taos -h first_ep --check返回状态码 2服务就绪随后在该节点上执行 root 密码初始化如需和/docker-entrypoint-initdb.d中的 SQL 初始化脚本最后执行create snode on dnode 1;创建流计算节点从节点td2/td3循环探测 firstEp 是否就绪就绪后通过taos -ppassword -h first_ep -P 6030 -s create dnode fqdn:serverPort;将自己注册进集群。这种设计保证了先起主节点、从节点自动加入的编排语义也是 Compose 三节点配置能够一键组网的根本原因。附加组件控制与初始化脚本除上述文档要点外入口脚本还提供了一组实用的控制开关本文依据 packaging/docker/bin/entrypoint.sh 源码整理环境变量默认值作用TAOS_DISABLE_ADAPTER0设为1时不启动 taosadapterREST 服务TAOS_DISABLE_KEEPER0设为1时不启动 taoskeeper监控服务TAOS_DISABLE_EXPLORER0设为1时不启动 taos-explorer可视化界面TZ空设置容器时区脚本会同步更新/etc/localtime与/etc/timezoneTAOS_ROOT_PASSWORDtaosdata自定义 root 密码3.3.8.8起需与数据库实际密码保持一致另外/docker-entrypoint-initdb.d目录支持挂载*.sql初始化脚本集群首个节点首次启动时会按文件名顺序执行执行失败会自动重试最多 5 次可用于预建数据库、预建账号等自动化场景。常见问题排查容器反复重启、日志提示 fqdn 相关错误检查是否为旧版本升级启动。v3.3.6.0后默认 fqdn 从buildkitsandbox变为localhost升级启动需显式指定旧 fqdn-e TAOS_FQDN旧值 -h 旧值。修改 root 密码后重启失效或报认证错误确认镜像版本属于3.3.8.8之后需提供TAOS_ROOT_PASSWORD若是3.3.6.6–3.3.8.4区间需在数据目录创建空的.docker-entrypoint-root-password-changed文件。健康检查失败3.4.1.0起使用taos-check startup检查服务是否就绪与taos-check service检查服务可用性。由于taos-check service使用与 taosd 相同的密码来源密码配置过期会同时破坏健康检查与其他基于 root 账号认证的组件务必先核对密码环境变量。从容器外部无法用原生客户端连接容器内服务使用容器 hostname 作为 FQDN外部原生客户端taos CLI、JDBC-JNI难以解析请改用 REST/WebSocket6041 端口或采用 host 网络模式 / 指定TAOS_FQDN的部署方式。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考