TDengine Docker 部署完全指南:单机、Host 网络与 Compose 集群

TDengine Docker 部署完全指南:单机、Host 网络与 Compose 集群 TDengine Docker 部署完全指南单机、Host 网络与 Compose 集群【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine导读本文是一份面向运维与开发者的 TDengine 容器化部署实战指南系统讲解如何通过docker run与docker-compose在 Docker 容器中启动 TDengine 服务、控制其行为并分别覆盖单机启动、Host 网络模式、指定 hostname 与端口启动以及 3 节点 Docker Compose 集群搭建。读完后你将掌握 TDengine 官方镜像的启动参数、TAOS_FQDN/TAOS_FIRST_EP等环境变量的正确用法、root 密码与镜像升级的版本差异规则以及健康检查工具taos-check的使用时机能够独立完成容器化 TDengine 的部署、验证与排障。本文内容以 Docker 部署文档中文版见 docs/zh/12-operations-and-tooling/02-operations/03-deployment/02-docker.md为核心骨架并结合仓库中的配置文件与启动源码进行原理级补充。Docker 部署的核心机制TDengine 官方镜像启动时默认激活 HTTP 服务你可以通过两种方式控制容器内服务的行为在docker run命令行中使用环境变量-e参数在docker-compose文件中为服务声明environment。这些环境变量与 taos.cfg 中的配置项一一对应。例如TAOS_FQDN对应fqdn、TAOS_FIRST_EP对应firstEp。从启动源码看tdengine 的启动程序source/dnode/mgmt/exe/dmMain.c显式支持两种环境注入方式DM_ENV_CMD The env cmd variable string to use when configuring the server, such as: -e TAOS_FQDNtd1. DM_ENV_FILE The env variable file path to use when configuring the server, default is ./.env, .env text can be TAOS_FQDNtd1.即除了docker run -e与 Compose 的environment外还支持通过./.env文件批量写入TAOS_FQDNtd1形式的配置适合在容器编排平台如 Kubernetes中统一管理配置项。镜像内默认数据与日志目录分别为目录用途说明/var/lib/taosTDengine 默认数据文件目录可通过配置文件dataDir修改位置建议通过-v挂载持久化/var/log/taosTDengine 默认日志文件目录可通过配置文件logDir修改位置建议挂载以便采集日志自定义密码、升级与健康检查的版本差异如果使用了自定义 root 密码需要注意 Docker 镜像在不同版本阶段的行为差异。后文所有涉及 hostname、docker compose 以及 Kubernetes 探针的场景凡是涉及 root 密码、升级或taos-check行为的均以上述规则为准3.3.6.6至3.3.8.4版本如果曾在旧版本镜像中修改过 root 密码需要在 data 目录默认/var/lib/taos下创建空文件.docker-entrypoint-root-password-changed后再启动容器touch /var/lib/taos/.docker-entrypoint-root-password-changed3.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 startup检查服务启动状态taos-check service检查服务可用性且会复用上述密码来源TAOS_ROOT_PASSWORD/TAOS_ROOT_PASSWORD_FILE。因此如果密码没有同步更新健康检查以及其他使用 root 账号鉴权的组件例如 taosAdapter、监控组件等都可能失败。这也意味着自定义密码一旦变更必须保证部署配置、健康检查与所有依赖 root 鉴权的组件使用同一份密码。启动单机 TDengine 容器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参数说明-d --name tdengine后台运行并命名容器为tdengine-v ~/data/taos/dnode/data:/var/lib/taos将主机的数据目录挂载到容器内默认数据目录实现数据持久化-v ~/data/taos/dnode/log:/var/log/taos挂载日志目录便于在主机侧查看与采集日志-p 6041:6041将容器内 HTTP 服务的端口 6041 映射到主机端口 6041。说明6041 同时是 TDengine RESTful/WebSocket 服务的默认端口。镜像默认启用 HTTP 服务因此在未显式映射 6030 的情况下通过 HTTP 接口即可完成建库、写入与查询。验证 HTTP 服务容器启动后使用 curl 请求 REST 接口验证服务是否可用默认 root 密码为taosdatacurl -u root:taosdata -d show databases localhost:6041/rest/sql返回information_schema、performance_schema等系统库列表即表示服务正常。进入容器使用 taos CLI执行以下命令在容器内访问 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 连接方式即映射并访问 6041 端口。在 host 网络模式下启动 TDengine运行以下命令可在 host 网络模式下启动 TDenginedocker run -d --name tdengine --network host tdengine/tsdb-ee在 host 网络模式下容器直接复用主机的网络栈因此可以使用主机的 FQDN建立连接而不是容器的 hostname。这种方式与在主机上使用systemctl start taosd启动 TDengine 的效果相同——服务直接监听主机的 6030 端口。若主机上已安装 TDengine 客户端可直接使用taosCLI 访问服务$ 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)从源码看firstEp与fqdn是 taos.cfg 中最核心的集群连接参数见 packaging/cfg/taos.cfgfirstEp指定 dnode 或 CLI 启动时主动连接的第一个 dnode 端点hostname:6030fqdn指定当前 dnode 所在主机的 FQDN可以是 IP 地址。host 网络模式下主机 FQDN 天然可解析因此无需额外配置。以指定的 hostname 和 port 启动 TDengine使用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 服务并使其监听 hostnametdengine由TAOS_FQDN指定将容器端口 6030 映射到主机端口 6030原生连接端口将容器端口段[6041, 6049]映射到主机的同一端口段TCP 与 UDP 均映射RESTful/WebSocket 及集群通信使用。如果主机上该端口段已被占用可以修改命令为指定主机上空闲的端口段。接下来需要确保 hostnametdengine在/etc/hosts中可解析将正确配置写入 hosts 文件echo 127.0.0.1 tdengine |sudo tee -a /etc/hosts最后通过taosCLI 以tdengine为服务器地址访问服务taos -h tdengine -P 6030升级启动的注意事项v3.3.6.0版本后默认fqdn已从buildkitsandbox变更为localhost。如果是全新启动没有任何问题但如果是升级启动运行容器时需要将-e TAOS_FQDNold_value和-h old_value指定为之前的 fqdn 值否则可能无法启动。特殊场景如果TAOS_FQDN被设置为与所在主机的 hostname 相同则效果与在 host 网络模式下启动 TDengine相同。使用 Docker Compose 启动 3 节点集群使用如下docker-compose.yaml配置可以启动一个 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指定每个节点的 FQDN。Compose 默认创建自定义网络服务名td1、td2、td3在集群内可作为域名解析因此三个节点以服务名作为各自 FQDN 即可互相通信TAOS_FIRST_EP指定节点主动连接集群中首个 dnode 的 endpoint效果与/etc/taos/taos.cfg中的firstEp参数一致对应 taos.cfg 中的firstEp hostname:6030见 packaging/cfg/taos.cfg。这里td2、td3均指向td1:6030即由 td1 作为集群的入口节点自定义密码如果集群使用了自定义 root 密码请在每个 service 中同步配置对应的密码环境变量TAOS_ROOT_PASSWORD或TAOS_ROOT_PASSWORD_FILE并确保其与数据库实际密码保持一致版本差异与升级要求以本文前述规则为准。启动集群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.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)三个 dnodetd1:6030、td2:6030、td3:6030状态均为ready说明集群已经正常组建。可以通过show mnodes、show dnodes等命令持续观察各节点的健康状态与 vnode 分布。端口与网络速查端口用途说明6030dnode 原生连接端口RPC对应serverPort集群内部通信与原生连接均使用6041RESTful / WebSocket 端口镜像默认启用 HTTP 服务对应 taos.cfg 中 WebSocket 配置段的serverPort 6041见 packaging/cfg/taos.cfg6041-6049RESTful/WebSocket 与扩展端口段按需映射UDP 段用于集群通信常见问题与排障建议1. 升级后容器无法启动检查是否为升级启动且曾使用自定义 fqdnv3.3.6.0之后默认 fqdn 改为localhost升级启动需显式指定-e TAOS_FQDNold_value和-h old_value检查是否修改过 root 密码3.3.6.6-3.3.8.4版本需在 data 目录 touch 空文件.docker-entrypoint-root-password-changed3.3.8.8及以上需通过TAOS_ROOT_PASSWORD/TAOS_ROOT_PASSWORD_FILE提供当前实际密码。2. 健康检查失败对于3.4.1.0及以上版本taos-check service复用 root 密码来源密码配置过期会导致健康检查及依赖 root 鉴权的组件失败请同步更新密码环境变量。3. 容器外无法访问 TDengine容器内 CLI 通过容器 hostname 连接容器外访问请优先使用 RESTful/WebSocket映射 6041 端口或改用 host 网络模式 / 显式设置TAOS_FQDN并保证 hostname 在/etc/hosts中可解析。4. 端口被占用主机端口段被占用时可修改-p映射为其他空闲端口段同时相应调整客户端的连接端口。总结通过 Docker 部署 TDengine 的核心要点可以概括为环境变量即配置TAOS_FQDN、TAOS_FIRST_EP、TAOS_ROOT_PASSWORD与 taos.cfg 配置项一一对应、版本差异决定升级路径root 密码与 fqdn 的处理规则随镜像版本不同而不同、网络模式决定连接方式桥接模式用 RESTful/WebSocket 最省事host 模式与TAOS_FQDN主机名可复用主机网络。掌握这些规则后无论是单机容器、多节点 Compose 集群还是 Kubernetes 中的 Pod 编排都可以按照统一的配置模型进行部署、升级与健康检查。【免费下载链接】tdengineTDengine is an open source, high-performance, cloud native time-series database optimized for Internet of Things (IoT), Connected Cars, Industrial IoT and DevOps.项目地址: https://gitcode.com/taosdata/tdengine创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考