企业官网建设流程全解析

TDengine Docker 部署实战：镜像启动、环境变量、健康检查与 Docker Compose 集群搭建

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

TDengine 官方镜像（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，启动完成后还会依次拉起 taosadapter（6041）、taoskeeper（6043）、taos-explorer（6060），并各自等待对应端口的/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/taos：TDengine 默认数据文件目录，可通过配置文件dataDir修改位置；
• /var/log/taos：TDengine 默认日志文件目录，可通过配置文件logDir修改位置；
• -p 6041:6041：将容器内 taosAdapter 的 HTTP 端口 6041 映射到主机同名端口。

数据与日志目录通过 volume 挂载到宿主机，是容器重建后数据不丢失的关键。

3.2 验证 HTTP 服务

容器启动后，可通过 RESTful 接口验证 HTTP 服务是否可用（默认账号root，默认密码taosdata）：

curl -u root:taosdata -d "show databases" localhost:6041/rest/sql

3.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_FQDN=tdengine \ -p 6030:6030 \ -p 6041-6049:6041-6049 \ -p 6041-6049:6041-6049/udp \ tdengine/tsdb-ee

上述命令做了三件事：

1. 容器内 TDengine 监听的 hostname 为tdengine；
2. 将容器端口 6030 映射到主机 6030（原生通信端口）；
3. 将容器端口段[6041, 6049]（TCP 与 UDP）映射到主机相同端口段——TCP 用于 HTTP/WebSocket 及 RPC，UDP 用于集群内节点心跳通信。若主机上该端口段已被占用，可修改命令改指主机空闲端口段；如果配置了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/hosts（127.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_FQDN=td1 td2: image: tdengine/tsdb-ee environment: - TAOS_FQDN=td2 - TAOS_FIRST_EP=td1:6030 td3: image: tdengine/tsdb-ee environment: - TAOS_FQDN=td3 - TAOS_FIRST_EP=td1:6030

配置要点：

• TAOS_FQDN为各节点指定独立 hostname（td1/td2/td3），compose 网络内部会为服务名自动完成 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.md
• Kubernetes 部署与探针配置：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