企业官网建设流程全解析

TDengine taosinstall 安装工具实战：单机与集群的自动化部署、升级完整指南

【免费下载链接】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

taosinstall是 TDengine 提供的集群级自动化安装与升级工具，用于解决传统安装包自带脚本只能单机安装、无法按集群批量编排的问题。本文以官方文档为主体，结合当前仓库中的服务配置模板（taos.cfg、taoskeeper.toml 等），系统讲解taosinstall的安装、升级命令参数、19 步安装流程、配置文件全字段语义以及停服/滚动升级两种升级模式，帮助读者在一台或多台节点上快速完成 TDengine（含 taosAdapter、taosKeeper、taosX、taosExplorer 等周边组件）的规模化部署与版本升级。

背景：为什么需要 taosinstall

TDengine 的安装包自带安装脚本，可以完成单机环境的基础安装。但在生产实践中，一个集群往往包含多台物理机或虚拟机，需要依次处理环境检查、安装包分发、配置下发、服务启停、dnode/mnode 创建、监控用户创建等一系列操作。若全部依赖人工逐节点执行脚本，效率低且容易出错。

taosinstall正是为这一场景设计：它以集群为单位自动完成安装与升级，支持：

:::warning 升级功能（尤其是滚动升级）当前仅推荐在测试环境使用，例如验证版本升级流程。生产环境使用前必须提前评估服务启动与可用性风险。 :::

工具本身属于 TDengine 企业版（Enterprise / tsdb）发行包中的组件，随企业版安装包一同发布，可执行文件名为taosinstall。

install 子命令：参数与安装流程

命令语法

taosinstall的安装子命令支持通过help参数查看完整语法：

usage: taosinstall install [-h] [--model {local,ssh}] [--config CONFIG] [--backend] [--check-md5] [--list LIST] [--lite] [--log-level {debug,info}] [--workers WORKERS] [--set-hostname] [--set-ips] [--replicas {2,3}] optional arguments: -h, --help show this help message and exit --model {local,ssh}, -m {local,ssh} connection model --config CONFIG, -f CONFIG Full path of config file --backend, -b Run process in backend --check-md5, -cm Check md5 of package --list LIST, -L LIST Comma-separated list of hostnames --lite Lite mode --log-level {debug,info}, -l {debug,info} Set log level, default: info (options: debug, info) --workers WORKERS, -w WORKERS Concurrency --set-hostname, -sh Set hostname --set-ips, -si Set IP/FQDN in /etc/hosts --replicas {2,3}, -r {2,3} Number of replicas

参数详细说明

• model：安装工具运行模式，分为local和ssh两种。
  • ssh 模式：集群节点间支持 SSH 通信时，可在任意节点上运行工具，工具会依次对所有配置的节点完成安装操作。
  • local 模式：节点间不支持 SSH 通信时，仅对工具运行所在机器完成安装操作。
  • 默认值为local。
• config：安装工具加载的配置文件路径，具体配置方式见下文「配置文件使用说明」。不指定时，配置文件默认取工具运行当前目录下的配置文件。
• backend：后台运行安装工具，默认为前台运行。
• check-md5：安装前检查安装包的 MD5 值，默认不检查。
• list：逗号分隔的节点列表，指定本次要部署的机器。前提是配置文件中指定的firstep已安装完成且服务运行正常；该参数主要为安装中断后继续安装剩余节点的场景预留，默认值为 None。
• log-level：输出日志级别，支持debug和info，默认为info。
• workers：集群安装部署时的并发数量，影响同时向多个节点分发文件的并发度，需根据机器资源情况调整，默认值为 50。
• set-hostname：根据配置文件的 FQDN 更新集群节点的 hostname，默认不更新。
• set-ips：根据配置文件的 FQDN 对应 IP 更新集群节点的/etc/hosts，默认不更新。
• replicas：部署 TDengine 的副本数量，支持双副本（2）和三副本（3），默认为三副本。
• version：打印安装工具版本信息（通过taosinstall version查看）。

安装流程（19 步）

安装工具的工作流为：复制并安装安装包 → 下发各服务配置文件 → 启动taosd→ 创建 dnode 与 mnode → 配置各组件 instanceId → 依次启动 taosAdapter、taosKeeper、taosX、taosExplorer → 创建监控用户。

💡 Note:安装前需确认 TDengine 各服务对应的配置文件中预设定参数是否正确，特别是数据和日志路径等信息。可参考仓库中的 taos.cfg 模板。

从步骤 4 可以看出，工具会基于预置模板动态生成taos.cfg中的集群关键参数。firstEp/secondEp/fqdn决定了集群的拓扑连接关系，而minReservedMemorySize用于控制 dnode 启动时保留的最小内存，防止内存不足影响数据写入。这些参数在仓库自带的 taos.cfg 模板中均有对应条目，例如firstEp hostname:6030、secondEp、fqdn hostname，用户可在预配置文件中提前写入其他静态参数（如dataDir、logDir、supportVnodes等），工具会把它们覆盖到所有 dnode 上。

步骤 17~19 的监控用户机制，与仓库中 taosKeeper 的配置结构相呼应：默认的 taoskeeper.toml 中[tdengine]段使用username/password连接 TDengine（默认 root/taosdata，端口 6041），并将监控数据写入[metrics.database]指定的log库。安装工具在部署完成后会将 keeper 的连接账号切换为专用 monitor 用户并重启，实现监控链路的权限收敛。

upgrade 子命令：停服升级与滚动升级

命令语法

usage: taosinstall upgrade [-h] [--model {local,ssh}] [--config CONFIG] [--backend] [--check-md5] [--list LIST] [--log-level {debug,info}] [--rolling-upgrade] optional arguments: -h, --help show this help message and exit --model {local,ssh}, -m {local,ssh} connection model --config CONFIG, -f CONFIG Full path of config file --backend, -b Run process in backend --check-md5, -cm Check md5 of package --list LIST, -L LIST Comma-separated list of hostnames --log-level {debug,info}, -l {debug,info} Set log level, default: info (options: debug, info) --rolling-upgrade, -r Rolling upgrade

参数详细说明

• model、config、backend、check-md5、list、log-level：语义与 install 子命令一致，可参考上文。
• rolling-upgrade：开启滚动不停服升级；目前仅推荐测试环境使用。默认（不携带该参数）为普通停服升级。
• version：打印安装工具版本信息。

💡 Note:由于客户现场环境复杂，启停服务过程可能遇到不可预期的问题，升级功能目前仅推荐在测试环境使用（例如验证版本升级）。若在业务环境使用，需要提前评估其风险。

停服升级流程

停服升级会先停止所有节点上的所有数据库服务，然后按照firstEp→secondEp→dnode3...的顺序依次完成升级与重启操作：

滚动升级流程

滚动升级不停服，按照「非 mnode 所在节点 → mnode 为 follower 的节点 → mnode 为 leader 的节点」的顺序依次执行升级与重启：

从执行顺序可以推断：非 mnode 节点承载普通 vnode，先升级对集群元数据影响最小；follower mnode 先于 leader 升级，可保证在 leader 升级的短暂窗口内仍有其他 mnode 对外提供服务，从而降低对客户端连接与元数据读写的影响。即便如此，滚动升级仍属于实验性能力，务必先在测试集群中演练。

配置文件使用说明

taosinstall的所有部署行为都由一个 INI 格式的配置文件驱动，它定义了三类信息：

1. 节点环境（SSH 访问信息、FQDN、副本拓扑）；
2. 安装物料（本地安装包路径、MD5 校验值、数据库连接凭证）；
3. 组件配置模板（taosd / taosadapter / taoskeeper / taosx / taos-explorer 各自的下发配置，以及监控账号与要安装的服务清单）。

💡 Note:节点间支持密码登录和免密登录两种方式。配置免密登录时，包括运行安装工具的当前节点在内，所有节点都要配置免密。

免密配置方法：

cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

完整配置示例

######################################################## # # # Configuration # # # ######################################################## # 安装部署 TDengine 的环境信息，支持免密登录和 SSH 登录两种方式，当环境配置了免密登录后可不用配置 password 信息 [test_env] # 节点间通过 SSH 协议访问 firstep=192.168.0.1||fqdn=tdengine1||username=root||password=123456||port=22 secondep=192.168.0.2||fqdn=tdengine2||username=root||password=123456||port=22 dnode3=192.168.0.3||fqdn=tdengine3||username=root||password=123456||port=22 # 节点间配置免密登录，包括运行安装工具的当前节点也要配置免密！！！ # firstep=192.168.0.1||fqdn=tdengine1||username=root||port=22 # secondep=192.168.0.2||fqdn=tdengine2||username=root||port=22 # dnode3=192.168.0.3||fqdn=tdengine3||username=root||port=22 # TDengine 安装包在本地所在全路径 [local_pack] package=/path_to_file/tdengine-tsdb-enterprise-3.3.x.x-Linux-x64.tar.gz md5=317f88bf13aa21706ae8c2d4f919d30f # oem 版本的版本名称，默认不使用 # [oem] # version=prodb # TDengine 的 Restful 连接信息 [database] username=root password=taosdata port=6030 rest_port=6041 # taosd 预配置文件, 该文件中配置会覆盖到所有 dnode 上对应配置文件 [taos_cfg] cfg_file=taos.cfg # taoskeeper 的预配置文件, 该文件中配置会覆盖到所有 dnode 上对应配置文件 [taoskeeper_cfg] cfg_file=taoskeeper.toml # taosadapter 的预配置文件, 该文件中配置会覆盖到所有 dnode 上对应配置文件 [taosadapter_cfg] cfg_file=taosadapter.toml # taosx 的预配置文件, 该文件中配置会覆盖到所有 dnode 上对应配置文件 [taosx_cfg] cfg_file=taosx.toml # explorer 的预配置文件, 该文件中配置会覆盖到所有 dnode 上对应配置文件 [taosexplorer_cfg] cfg_file=explorer.toml # 监控用户 monitor 的配置信息 [monitor_user] username=monitor password=Taosmonitor_125# [td_services] taosd taos taosadapter taoskeeper taosx taos-explorer

配置段落逐项说明

• [test_env]：集群节点列表。每一行以key=IP||fqdn=FQDN||username=用户||password=密码||port=端口的管道分隔格式描述一个节点：
  • firstep/secondep：集群第一、第二个节点的连接信息，安装工具会依据它们生成taos.cfg中的firstEp/secondEp（详见 taos.cfg 中# firstEp hostname:6030与# secondEp条目）；
  • dnode3、dnode4……：其余 dnode 节点，可依此类推扩展；
  • 使用免密登录时，可省略password字段；
  • 注意官方示例中节点字段顺序为「IP || fqdn || username || password || port」，配置时保持该顺序即可。
• [local_pack]：本地安装包与校验信息：
  • package：TDengine 企业版（tsdb）安装包在运行工具的本机上的完整路径；
  • md5：安装包的 MD5 值，配合--check-md5在安装前校验包完整性。
• [oem]：OEM 版本名称，默认不使用；需要 OEM 定制版本时填写version=prodb之类的名称。
• [database]：安装工具连接 TDengine 的 REST 信息（用于建库、建用户等控制操作）：
  • username/password：数据库连接账号，默认 root / taosdata；
  • port：原生连接端口，默认 6030；
  • rest_port：REST 端口，默认 6041。
• [taos_cfg]/[taosadapter_cfg]/[taoskeeper_cfg]/[taosx_cfg]/[taosexplorer_cfg]：各服务组件的预配置模板文件。工具会将cfg_file指向的模板文件下发并覆盖到所有 dnode 上对应的正式配置文件。仓库中可参考的模板包括：
  • taosd：packaging/cfg/taos.cfg（含firstEp、secondEp、fqdn、serverPort、dataDir、logDir、supportVnodes、各模块debugFlag等参数）；
  • taoskeeper：tools/keeper/config/taoskeeper.toml（含host/port监听地址、[tdengine]连接段、[metrics.database]监控库选项、[log]日志段等），企业版可参考 taoskeeper_enterprise.toml（额外包含[audit]审计段）。
• [monitor_user]：监控账号配置。工具在安装流程第 17~19 步创建该用户，并将 taoskeeper 的数据库连接切换为该账号后重启，使监控数据采集使用独立的最小权限账号。
• [td_services]：要安装并纳入管理的服务清单，默认包含taosd、taos、taosadapter、taoskeeper、taosx、taos-explorer，对应升级流程中统一停止与启动的服务集合。

应用示例

以下示例均假定taosinstall位于当前目录，且对应的配置文件已按上文格式准备好。

1. 在工具所在节点安装数据库（单机 local 模式）

./taosinstall install -m local

2. 在集群所有节点安装数据库，日志级别配置为 debug

./taosinstall install -m ssh -l debug

3. 指定配置文件并在集群所有节点安装数据库

./taosinstall install -m ssh -f /path_to_file/install.cfg

4. 在集群指定节点安装数据库（-L后跟逗号分隔的节点名）

./taosinstall install -m ssh -L server1,server2

5. 停服升级数据库

./taosinstall upgrade -m ssh

6. 滚动升级数据库

./taosinstall upgrade -m ssh -r

7. 其余常见用法

# 校验安装包 MD5 后安装（ssh 模式） ./taosinstall install -m ssh -f /path_to_file/install.cfg --check-md5 # 以 100 并发分发安装包 ./taosinstall install -m ssh -f /path_to_file/install.cfg -w 100 # 安装完成后更新节点 hostname 与 /etc/hosts ./taosinstall install -m ssh -f /path_to_file/install.cfg --set-hostname --set-ips # 以双副本部署 ./taosinstall install -m ssh -f /path_to_file/install.cfg -r 2 # 后台运行安装任务 ./taosinstall install -m ssh -f /path_to_file/install.cfg -b # 查看安装工具版本 ./taosinstall version

使用建议与注意事项

1. 升级仅限测试环境：停服升级与滚动升级都会触碰服务的启停，现场环境复杂，请先在测试集群完整演练，确认服务启动与数据可用性无风险后再评估是否用于业务环境。
2. 先核对预配置模板：安装前务必核对各组件cfg_file中的静态参数，尤其是dataDir、logDir等路径配置，避免数据落到错误目录。
3. 合理设置并发与副本数：--workers默认 50，分发安装包时可根据节点数与网络带宽调整；--replicas支持 2 或 3，默认三副本。
4. 主机名与 hosts 的一致性：若节点间依赖 FQDN 通信，建议使用--set-hostname与--set-ips让集群节点的 hostname 与/etc/hosts保持一致，否则可能出现节点间无法解析对端的问题。
5. 免密登录的完整性：ssh 模式下，包括运行工具的当前节点在内的所有节点都必须配置免密登录，否则工具无法在节点间建立连接。
6. 中断续装：若安装中途失败，可待firstep节点安装并运行正常后，使用--list指定剩余节点继续安装，避免整集群重来。
7. 监控链路：安装完成后，taoskeeper 使用[monitor_user]中配置的 monitor 账号采集监控数据，请妥善保管该账号密码，并可在 taoskeeper.toml 的[metrics.database]段按需调整监控库的vgroups、buffer、keep等参数。

总结

taosinstall将 TDengine 集群部署从「逐节点手工安装」提升为「一份配置、一条命令」的自动化流程：install子命令覆盖单机、全集群、指定节点三类安装场景，并自动完成 taosd 配置动态生成、dnode/mnode 创建、各组件 instanceId 配置与监控用户创建；upgrade子命令提供停服升级与滚动升级两种模式，配合--list、--workers、--check-md5等参数可灵活应对部署中断续装、批量分发与包完整性校验等实际需求。对于需要在多节点环境规模化部署 TDengine 的运维与测试团队，该工具是显著提升效率的实用选择。

【免费下载链接】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