TDengine 安装前检查工具 taosprecheck 详解：环境预检命令、配置文件与全量检查项解析

TDengine 安装前检查工具 taosprecheck 详解：环境预检命令、配置文件与全量检查项解析

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

TDengine 的集群部署对操作系统的内核参数、网络、时区、安全策略等环境要素有明确依赖。本文以 TDengine 官方文档中的安装前检查工具taosprecheck为主体，完整解析其命令行参数、配置文件的每个配置节、12 大类检查项的设计意图，以及检查结果文件的产出与应用示例，帮助你在一键安装 TDengine 之前系统性地消除环境隐患，并将预检结果作为后续预配置（taospreset）与安装部署（taosinstall）的输入依据。

一、背景与工具定位

TDengine 的安装部署对环境系统有一定的依赖和要求，安装部署前需要对环境进行安装前检查，提前发现环境问题。taosprecheck就是 TDengine 巡检工具族中的“安装前检查”工具，其定位是：只检查、不改动——它按照配置文件描述的目标环境，逐项核对节点的真实系统状态，输出检查报告与配置建议，供实施人员判断环境是否满足部署条件。

在 TDengine 巡检工具族中，各工具分工明确（详见 巡检工具总览）：

典型的落地流程是：taosprecheck检查 → 人工确认报告 →taospreset预配置整改 →taosinstall安装部署。检查与预配置共用同一套节点配置文件，检查项的判据即预配置的目标值，二者天然衔接（安装前预配置工具 taospreset）。

使用限制与支持范围

根据 巡检工具文档 的说明，使用该工具需要满足以下前提，这些限制同样适用于taosprecheck：

• 版本范围：巡检工具目前仅支持企业版用户，暂不对社区版开放；从仓库结构看，README 中亦说明社区版构建不打包taosinspect等独立仓库提供的组件，与“企业版配套交付”的定位一致。
• 支持的平台：Kylin V10、Ubuntu（20.04.2）、CentOS（7.9）、LinxOS（6.0.99）、openEuler（23.09）、Debian（12）。若在其它平台或版本上运行遇到问题，需联系对接的交付人员。
• 支持的 TDengine 版本：3.1.x.x 及以上版本。
• 运行前提条件：
  • 运行工具需要 root 权限；普通用户运行则需要 sudo 权限；
  • 配置免密登录的环境，运行工具的当前节点也需要配置自身免密；
  • 运行环境 glibc 版本要求：glibc 2.17 及以上（x64 架构）、glibc 2.27 及以上（ARM 架构）；
  • 配置的 FQDN 和 IP 地址必须提前配置到/etc/hosts文件；
  • 集群节点之间的 SSH 服务必须启用；如果无法启用 SSH 服务，则只能通过 local 模式在每个节点上单独运行工具。

二、命令行用法与参数详解

工具支持通过 help 参数查看支持的语法，帮助输出如下：

usage: taosprecheck [-h] [--model {local,ssh}] [--config CONFIG] [--backend] [--result RESULT] [--version] [--log-level {debug,info}] Pre-check for Database installation optional arguments: -h, --help show this help message and exit --model {local,ssh}, -m {local,ssh} connection model, default: local --config CONFIG, -f CONFIG Full path of test config file --backend, -b Run process in backend. default: False --result RESULT, -r RESULT Result directory. default: ./ --version, -v Show version --log-level {debug,info}, -l {debug,info} Set log level, default: info (options: debug, info)

各参数详细说明：

从参数设计可以推断其工作方式：-m ssh模式下工具会以配置文件中声明的所有节点为检查对象，借助 SSH 通道逐一采集各节点的系统信息；-m local模式则只检查运行工具的本机，适用于节点间无法打通 SSH 的场景（此时需要在每个节点分别执行，再人工汇总多份报告）。-b选项适合节点较多、单轮检查耗时较长的场景，可挂到screen/tmux或 nohup 会话之外异步执行。

三、配置文件使用说明

taosprecheck的配置文件采用 INI 风格，定义了“目标环境”的全部描述。工具会依据这份目标环境逐项核对节点现状。一个完整的配置示例如下（保留官方文档原样）：

# 安装部署 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||username=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 # 系统时区，工具会按照下面配置修改系统时区 [timezone] tz=Asia/Shanghai # 系统服务状态，工具会按照下面配置关闭对应的系统服务 [services] firewall=inactive selinux=inactive # coredump 配置，工具会按照下面配置 coredump 的生成路径 [coredump] kernel.core_pattern=/data/taos/core/core-%%e-%%p # /etc/sysctl.conf 中系统参数，工具会按照下面配置修改系统参数值 [sys_vars:/etc/sysctl.conf] fs.nr_open=2147483584 fs.file-max=2147483584 net.ipv4.ip_local_port_range=10000 65534 # /etc/security/limits.conf 中系统参数，工具会按照下面配置修改系统参数值 [sys_vars:/etc/security/limits.conf] * soft nproc=65536 * soft nofile=2147483584 * soft stack=65536 * hard nproc=65536 * hard nofile=2147483584 * hard stack=65536 root soft nproc=65536 root soft nofile=2147483584 root soft stack=65536 root hard nproc=65536 root hard nofile=2147483584 root hard stack=65536 # 预安装软件列表 [app_list] screen tmux gdb fio iperf iperf3 sysstat net-tools jansson snappy ntp chrony tree wget

勘误提示：官方示例中dnode3一行把password误写成了username（username=root||username=123456），实际编写配置时应为password=123456，否则该节点的登录凭据无效。

各配置节逐项说明

1.[test_env]：节点环境信息

每行描述一个节点，字段以||分隔：ip||fqdn||username||password||port。支持两种认证方式：

• SSH 口令登录：填写password字段；
• 免密登录：提前配置好 SSH 密钥后，可以省略password字段（如示例中被注释的部分）。

节点名（firstep、secondep、dnode3等）可自定义，其 FQDN 会用于集群内部的域名寻址，因此巡检工具文档要求所有 FQDN 和 IP 必须提前写入各节点的/etc/hosts。port为 SSH 端口，默认 22，若目标环境修改了 SSH 端口需如实填写。

2.[timezone]：系统时区

tz=Asia/Shanghai声明了集群统一的时区。时区一致性直接影响时序数据的写入、查询与流计算触发时间，因此检查工具会核对各节点当前时区是否与该配置一致。

3.[services]：系统服务状态

声明需要处于inactive状态的系统服务：

• firewall=inactive：防火墙会拦截 6030（TDengine 默认服务端口）及节点间同步流量，生产集群通常依赖统一安全组或独立防火墙策略管理网络，故工具要求本地防火墙关闭并据此检查；
• selinux=inactive：SELinux 的强制访问控制会干扰服务对数据目录、socket 的访问，检查工具会确认其状态与配置一致。

4.[coredump]：coredump 路径

kernel.core_pattern=/data/taos/core/core-%%e-%%p指定了 core 文件的统一生成路径与命名格式（%e为进程名、%p为进程号，%%是转义后的字面量%）。TDengine 出问题时 core 文件是排障的关键证据，将 coredump 路径固定到独立数据盘既便于收集，也避免 core 文件写满系统盘。检查项即核对各节点kernel.core_pattern是否已按该值配置。

5.[sys_vars:/etc/sysctl.conf]：内核参数

• fs.nr_open=2147483584与fs.file-max=2147483584：将系统级文件描述符上限提升到约 21 亿量级。TDengine 的 taosd 进程需要维护大量文件句柄（SMA/RDB 数据文件、WAL、网络 socket 等），文件描述符不足会导致“too many open files”类故障，这两项参数是高并发时序场景的基础保障；
• net.ipv4.ip_local_port_range=10000 65534：扩大本地临时端口范围，避免节点间大量长连接/短连接复用端口时出现端口耗尽。

6.[sys_vars:/etc/security/limits.conf]：用户级资源限制

对*（所有用户）和root分别配置 soft/hard 三组上限：

• nproc=65536：单用户可创建进程/线程数上限，保证多节点、多进程组件运行不触及进程数天花板；
• nofile=2147483584：单用户文件描述符上限，与上面的fs.nr_open/fs.file-max配套，避免“系统上限够、单用户被限住”的错配；
• stack=65536（KB）：线程栈大小，为深调用栈场景留足余量。

检查工具会比对各节点实际limits.conf中的值是否与配置一致。

7.[app_list]：预安装软件列表

screen、tmux、gdb、fio、iperf/iperf3、sysstat、net-tools、jansson、snappy、ntp、chrony、tree、wget等工具清单，覆盖了部署交付（screen/tmux/wget）、故障排查（gdb）、性能诊断（fio、iperf、sysstat、net-tools）和时间同步（ntp、chrony）三类用途。检查时工具会核对这些软件是否已安装，若已安装则记录其版本，便于在报告里留档追溯。

四、安装前检查范围全解

taosprecheck共覆盖 12 大类检查项，完整清单如下：

各类检查项背后的工程含义值得结合 TDengine 的部署形态理解：

• CPU / 内存：TDengine 作为内存与 CPU 密集型的时序引擎，SMA 索引构建、压缩编码与查询执行都高度依赖这两项资源，报告记录型号与容量后，实施人员可据此判断资源配置是否匹配数据规模；
• 磁盘配置：磁盘类型（SSD/HDD）、挂载点与 fsblk 信息决定了数据目录的落盘位置与可靠性；磁盘使用情况则用于评估剩余容量能否承载预期写入量；
• 网络配置：SSH 服务与 22 端口是ssh模式逐节点采集的前提；网络带宽检查为集群节点间同步、跨节点查询提供容量基线（该检查的基准带宽测试可与taosperf的 IO/网络基准性能测试互补）；
• 系统配置：系统名称、时区、防火墙与 SELinux 状态对应配置文件中的[timezone]与[services]节，确保集群时区统一、网络策略不阻塞业务端口；
• coredump / 系统参数 / SWAP：分别对应[coredump]与两个[sys_vars:...]节，以及交换分区的显式状态盘点（时序库通常要求关闭或严格控制 SWAP，防止数据页被换出造成毛刺）；
• 域名解析：集群以 FQDN 相互寻址，/etc/hosts缺少任一节点条目都会导致 mnode/vnode 注册或同步失败，因此单独列出；
• KYSEC：麒麟系统特有的安全模块（与 SELinux 类似的强制访问控制框架），仅在 Kylin 环境下生效；
• 时间同步：时序数据库对节点间时钟一致性极其敏感——乱序写入、流计算窗口触发、集群仲裁都可能受时钟漂移影响，因此工具不仅检查 ntp/chrony 是否安装，还会计算各节点间的时间偏差并精确到秒，给出可量化的结论。

五、结果文件

安装前检查工具运行后会在工具运行当前目录（即--result指定目录）下生成两个文件：

precheck_report.md回答“环境现在是什么状态”，precheck_advice.md回答“离可部署还差什么”。建议将两份文件纳入交付文档：前者作为部署前环境快照留档，后者作为整改清单跟踪闭环。若使用-r指定了独立结果目录，文件会生成在该目录下，便于多轮检查的版本对比。

六、应用示例

在工具所在节点以 local 模式执行安装前检查（默认模式、默认读取当前目录配置文件、结果输出到当前目录）：

./taosprecheck

以 SSH 模式在所有节点执行安装前检查：

./taosprecheck -m ssh

指定配置文件并以 SSH 模式在所有节点执行安装前检查：

./taosprecheck -m ssh -f /path_to_file/precheck.cfg

以 SSH 模式在所有节点执行安装前检查，开启日志 debug 级别（排查工具自身行为时使用）：

./taosprecheck -m ssh -l debug

将以上示例组合，一个常见的企业级多节点交付检查流程是：

1. 将precheck.cfg（含[test_env]全部节点、[timezone]、[services]、[coredump]、两个[sys_vars:...]、[app_list]）放到执行节点；
2. 在任一节点执行./taosprecheck -m ssh -f precheck.cfg -r ./precheck_$(date +%Y%m%d)，得到precheck_report.md与precheck_advice.md；
3. 按建议清单整改（或由同族的 taospreset 按同一份配置文件自动完成时区、服务、sysctl、limits、coredump 等预配置）；
4. 复跑taosprecheck确认全部检查项通过，再进入 安装部署工具 taosinstall 的部署阶段；部署稳定后可周期性运行 例行巡检工具 taosinspect 保持环境健康。

七、基于仓库的补充说明

• 当前开源仓库仅包含该工具的用户文档（中文文档 与 英文文档），taosprecheck的可执行程序与实现源码未随开源仓库发布，属于企业版配套交付物——这与 巡检工具总览 中“仅支持企业版用户”的声明一致。因此本文所有检查项、参数行为均以官方文档描述为准；
• 与taosprecheck同族的taospreset、taosinspect命令行结构高度同构（均提供-m、-f、-b、-r、-v、-l等参数），意味着同一份precheck.cfg可在预检与预配置之间直接复用，降低了多阶段交付的配置维护成本；
• 若需要在社区版环境下做类似的环境自查，可按本文“安装前检查范围”一节的清单手工核对各节点：uname（系统/内核）、timedatectl（时区）、systemctl status firewalld/iptables与getenforce（服务状态）、cat /proc/sys/kernel/core_pattern（coredump）、sysctl fs.nr_open fs.file-max net.ipv4.ip_local_port_range、ulimit -n/-u/-s（limits）、/etc/hosts（域名解析）以及 ntp/chrony 的节点间时间差，即可覆盖文档所列的大部分检查点。

适用前提小结：企业版用户、TDengine 3.1.x 及以上版本、root 或 sudo 权限、glibc 满足架构要求、FQDN 已写入/etc/hosts、节点间 SSH 可达（否则用 local 模式逐节点执行）——满足以上条件即可在 TDengine 集群正式部署前，用taosprecheck完成一次系统化、可留档、可复跑的环境预检。

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