TDengine 源码构建实战指南：从 CMake 编译、自动化测试到社区版打包的完整开发流程

TDengine 源码构建实战指南：从 CMake 编译、自动化测试到社区版打包的完整开发流程

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

本文以 TDengine 官方开发者指南（README-JP.md）为骨架，面向希望自己动手从源码构建、测试、打包并贡献代码的开发者，完整讲解 TDengine 的系统要求、CMake 构建选项、单元/集成测试、社区版 tarball 打包、安装与运行全流程。读完本文，你将掌握在 Linux/macOS 上复现 TDengine 官方构建流程的能力，并能借助仓库中的 cmake/options.cmake、packaging/pack_community_tar.sh 与 test/README.md 深入理解每个环节的底层实现。

1. 项目定位：面向开发者的 TDengine 开源版本

TDengine 是一款为物联网（IoT）、车联网与工业物联网（IIoT）设计的开源、高性能、云原生且内置 AI 能力的时序数据库（TSDB），可高效实时地摄取、处理并分析每天 TB 乃至 PB 级的海量传感器数据。围绕这一核心定位，官方 README 总结了以下关键特性：

• 高性能：通过解决高基数（high cardinality）问题支撑数十亿数据采集点，并在数据写入、查询与压缩性能上具备竞争力；
• 简化方案：内置缓存、流式计算、数据订阅与 AI Agent 能力，降低系统设计与运维复杂度；
• 云原生：原生分布式设计、分片与分区、计算存储分离、RAFT 协议、Kubernetes 部署支持；
• AI 加持：内置 AI Agent TDgpt，可连接时序基础模型、大语言模型与机器学习算法，提供预测、异常检测、缺失值补全与分类能力；
• 易用与易分析：超级表（super table）、时间窗口分区、预计算等机制让数据探索与整形高效简单；
• 开源：核心模块（含集群功能与 AI Agent）均在开源许可下提供。

本仓库默认版本号可在 cmake/version.cmake 中查看（默认3.4.2.5.alpha），许可协议为 AGPL-3.0（见 LICENSE）。若想了解最新组件 TDgpt 的细节，可阅读 tools/tdgpt/README.md。

本文档其余内容聚焦于官方 README 中面向开发者的部分：如何自行构建、测试、打包、安装并运行 TDengine——这正是从源码贡献者的视角进入项目的最佳路径。

2. 构建前提条件

2.1 系统要求

官方指南给出的最低系统要求如下：

TDengine 的构建与测试主要面向 Linux 完成；macOS 构建仅作为本地开发支持；开源树中 Windows 支持有限，因此需要可复现构建时，请默认选择 Linux。

2.2 构建工具安装

Ubuntu/Debian：

sudo apt-get update sudo apt-get install -y build-essential cmake git

CentOS/RHEL：

sudo yum groupinstall -y "Development Tools" sudo yum install -y cmake3 git

注意：构建外部依赖需要CMake 3.21 及以上版本。若发行版自带的 CMake 过旧，请从官方渠道安装新版本后再继续。

根据构建目标不同，还可能用到以下工具：

• 运行test/下的测试框架需要Python 3；
• 构建 taosAdapter、taosKeeper 等组件需要Go 1.23 及以上。

2.3 可选工具

• ccache—— 加速重复构建：sudo apt install ccache
• Conan 2.x—— 仅在构建taos-gen组件时需要：pip3 install conan

3. 从源码构建 TDengine

3.1 快速开始

获取源码后，在仓库根目录执行：

mkdir debug && cd debug cmake .. -DBUILD_CONTRIB=ON # 首次构建：-DBUILD_CONTRIB=ON 为必需 make -j$(nproc)

重要首次从源码构建时必须使用-DBUILD_CONTRIB=ON。该选项会下载 xxhash、zstd、lz4 等外部依赖并在.externals/下完成构建；第二次及以后的构建通常可以省略该标志，缓存产物会被自动复用。

常用的变体命令：

# 附带 CLI 工具的 Release 构建 cmake .. -DBUILD_CONTRIB=ON -DCMAKE_BUILD_TYPE=Release -DBUILD_TOOLS=ON make -j$(nproc) # macOS 上的等价并行构建 cmake .. -DBUILD_CONTRIB=ON -DCMAKE_BUILD_TYPE=Release cmake --build . --parallel "$(sysctl -n hw.ncpu)"

3.2 构建选项详解

下表默认值取自 README-JP，对应 cmake/options.cmake 中定义的独立开源版默认配置：

源码一致性说明：上表默认值以官方 README 为准，个别选项在 cmake/options.cmake 中实际定义可能略有出入。例如BUILD_LIBSASL在源码第 140 行实际默认值为ON，BUILD_USE_PUBLIC_DEPS在文件中被定义了两次（standalone 分支为ON、末尾为OFF）。以当前仓库源码实际为准是最稳妥的做法。

典型组合示例：

cmake .. -DBUILD_CONTRIB=ON -DCMAKE_BUILD_TYPE=Release -DBUILD_TOOLS=ON

3.3 构建产物

以debug/为构建目录时，默认构建树结构如下：

• 二进制位于debug/build/bin/：
  • taosd—— TDengine 服务端守护进程
  • taos—— TDengine CLI 客户端
  • taosBenchmark—— 基准测试工具（需BUILD_TOOLS=ON）
  • taosdump—— 导入/导出工具（需BUILD_TOOLS=ON）
• 库文件位于debug/build/lib/：
  • Linux 下为libtaos.so（或对应平台的客户端库）

4. 测试

4.1 单元测试

TDengine 使用 googletest 编写单元测试，开启BUILD_TEST=ON后通过 CTest 驱动：

cd debug cmake .. -DBUILD_CONTRIB=ON -DBUILD_TEST=ON make -j$(nproc) ctest --output-on-failure

部分单独的测试二进制也会输出到debug/build/bin/。

4.2 集成测试

TDengine 在test/目录下提供了一套 Python 端的端到端测试框架。README-JP 给出了传统流程：先构建服务器与工具，再用测试配置启动taosd，最后运行系统测试用例：

# 先构建服务器与工具 cd debug cmake .. -DBUILD_CONTRIB=ON -DBUILD_TOOLS=ON -DBUILD_TEST=ON make -j$(nproc) # 以测试配置启动 taosd ./build/bin/taosd -c test/cfg &

以当前仓库为准，集成测试框架已演进为基于 Pytest 的新框架（详见 test/README.md），具备以下特点：

• 基于Pytest，支持 fixture、参数化测试与插件扩展；
• 集成原有测试框架的公共函数，实现既有代码与工具的无缝复用；
• 支持通过YAML 文件灵活部署服务器，可自定义测试环境与配置；
• 测试结束后自动生成Allure 报告；
• 测试用例存放在 test/cases 下，按主题分目录组织（如09-DataQuerying/、17-DataSubscription/等）。

本地运行新框架测试的基本步骤：

cd test pip3 install -r requirements.txt # 在已启动 taosd 的环境中执行 pytest 用例 pytest cases/...

仓库还提供了批量执行脚本 test/run_tests.sh：它接收一个测试用例列表文件作为参数，逐行解析pytest ...命令并执行，将结果写入test_logs/case_result.txt与test_logs/run_tests.log，通过日志中的successfully executed或AsanFileSuccessLen: 1标记判定用例 PASS/FAILED，若环境中安装了 Allure 还会自动生成报告（见 test/run_tests.sh）。CI 侧的相关脚本位于 test/ci（如pytest.sh、run.sh、run_case.sh与用例清单cases.task）。

5. 打包与发布

5.1 社区版 tarball 打包

README-JP 中介绍了通过打包脚本生成开源社区版 tarball 的流程。以当前仓库为准，该脚本实际位于 packaging/pack_community_tar.sh，其 Usage 摘要如下（对应脚本头注释 packaging/pack_community_tar.sh）：

./pack_community_tar.sh -c <compile_dir> -n <version> [-m <compat_version>] [-V <verType>]

首先完成构建：

mkdir debug && cd debug cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_CONTRIB=ON -DBUILD_TOOLS=ON make -j$(nproc)

然后在仓库根目录运行打包脚本（README-JP 中的版本号示例3.3.6.0仅为演示，当前仓库 cmake/version.cmake 的默认版本为3.4.2.5.alpha）：

cd .. ./packaging/pack_community_tar.sh -c debug -n 3.3.6.0

可选参数：

• -m <compatible_version>—— 兼容版本号，默认3.0.0.0
• -V <stable|beta|preRelease>—— 版本类型，默认stable

完整示例：

./packaging/pack_community_tar.sh \ -c debug \ -n 3.3.6.0 \ -m 3.0.0.0 \ -V stable

打包脚本的关键校验与行为（来自源码级核查 packaging/pack_community_tar.sh）：

• 版本格式校验：-n必须匹配^([0-9]+\.){2,4}[0-9]+$（3～5 段数字）；-V仅接受stable、beta、preRelease（第 68-78 行）；
• 必需文件校验：构建目录下必须存在bin/taosd、bin/taos、lib/libtaos.so、lib/libtaosnative.so，以及packaging/tools/下的install.sh、install_client.sh、remove.sh、remove_client.sh和packaging/cfg/taos.cfg（第 135-166 行）；
• 架构自动检测：x86_64→x64、aarch64/arm64→arm64、mips64*→mips64、loongarch64、riscv64，未知架构按原样使用（第 110-123 行）；
• 仅支持 Linux：脚本检测到非 Linux 环境会直接报错退出（第 103-108 行）。

生成产物输出到仓库根目录下的release/目录：

release/TDengine-server-<version>-Linux-x64.tar.gz release/TDengine-client-<version>-Linux-x64.tar.gz

若-V指定为beta或preRelease，文件名会带上版本类型后缀（如TDengine-server-3.3.6.0-beta-Linux-x64.tar.gz）。

两层 tarball 结构（与既有打包流程保持一致）：

• 外层为分发用 tarball；
• 内层为包含bin/、cfg/、inc/的package.tar.gz。

以 server 包为例，外层 tarball 还包含：

• driver/：libtaos.so.<version>、libtaosnative.so.<version>以及记录兼容版本的vercomp.txt；
• examples/c：C 语言示例代码；
• install.sh：安装脚本（脚本会将verMode=cluster替换为verMode=edge，并通过patch_server_install_messages去除社区包中不存在的 keeper/explorer 安装提示，见 第 179-191 行）；
• start-all.sh/stop-all.sh：社区版仅管理taosd一个服务的启停脚本。

server 包中的bin/包括核心二进制taosd、taos，以及存在时才打包的taosBenchmark、taosdump、taosudf；inc/包含 include/client/taos.h、include/common/taosdef.h、include/util/taoserror.h、include/util/tdef.h、include/libs/function/taosudf.h 等头文件。client 包结构类似，但核心二进制为taos，配套install_client.sh与get_client.sh等脚本。

需要特别说明的是：社区版 tarball 只打包本仓库构建的产物——taosd、taos、taosBenchmark、taosdump、taosudf、libtaos.so、libtaosnative.so、头文件与安装脚本。像taoskeeper、taos-explorer、taosx、各语言连接器、taosinspect等位于其他仓库或需要独立构建流程的组件，不在打包范围内。

5.2 官方安装包

官方安装包由 packaging/tools/makepkg.sh 生成（位于packaging/tools/目录），该脚本按compile_dir、version、build_time、cpuType、osType、verMode、verType、pagMode、versionComp等参数生成适用于各操作系统的安装包，并区分 cluster（企业版）/cloud/edge 等模式。社区版开发者主要使用 5.1 节的pack_community_tar.sh流程。

6. 安装与运行

6.1 从安装包安装

对于由makepkg.sh生成的官方安装包：

tar -xzf TDengine-server-<version>-Linux-x86_64.tar.gz cd TDengine-server-<version> sudo ./install.sh

6.2 从源码直接安装

不经过打包，直接从本地源码构建结果安装：

cd debug sudo make install

6.3 启动与连接

安装完成后启动服务端并连接：

# 安装后启动服务 sudo systemctl start taosd # 通过 CLI 连接 taos

若想从构建树快速本地运行：

cd debug ./build/bin/taosd -c test/cfg

随后在另一个 shell 中执行：

cd debug ./build/bin/taos -c test/cfg

6.4 配置文件要点

-c指定的配置目录可参考打包用的默认配置 packaging/cfg/taos.cfg，其中集中了服务端与 WebSocket 两大类配置项。服务端侧关键项包括：

• firstEp—— 集群中首个 dnode 的端点（默认hostname:6030），CLI 或 dnode 启动时连接；
• fqdn—— 本 dnode 所在主机的 FQDN，可为 IP；
• serverPort—— dnode 对外服务端口（默认6030）；
• logDir/dataDir/tempDir—— 日志、数据与临时文件目录（Linux 下默认/var/log/taos、/var/lib/taos、/tmp/）；
• minimalDataDirGB—— 磁盘剩余空间低于该值时 dnode 拒绝启动（默认2.0GB）；
• numOfLogLines/logKeepDays/asyncLog—— 日志行数上限、保留天数与异步写日志开关；
• debugFlag系列 —— 按模块（timer/util/rpc/query/dnode/vnode/wal/sync 等）分别设置调试级别（131 仅警告与错误、135 增加 debug、143 增加 trace、199/207 同时输出到屏幕与文件）。

WebSocket 配置段（端口6041）则包含wsTlsMode（TLS 模式 0～3）、wsTlsVersion、wsTlsCa（CA 证书路径或 PEM 内容）、adapterList（taosAdapter 地址列表，用于负载均衡与故障转移）以及connRetries、retryBackoffMs、retryBackoffMaxMs（连接失败重试与退避策略）等。

7. 覆盖率

README-JP 介绍了本地生成 HTML 覆盖率报告的方式；以当前仓库为准，覆盖率相关工作已容器化到 test/ci/cov/ 目录，其使用方式记录在 test/ci/cov/README.md 中：

# 构建并启动容器 docker-compose up -d # 查看容器状态 docker-compose ps # 查看 cron 任务日志 docker-compose exec tdengine-coverage-cron cat /var/log/cron/cron.log

容器基于python:3-slim镜像，定时任务安排为：10:10运行测试报告、10:12运行带清理的测试报告、10:50执行清理；日志存放在宿主机的./cron_logs目录。需要手动验证时，可进入容器执行：

docker-compose exec tdengine-coverage-cron bash python3 /home/tdengine_coverage_alarm.py -test

覆盖率相关脚本（run_coverage_container.sh、run_coverage_diff.sh、coverage.task、tdengine_coverage_alarm.py等）均可在此目录中查阅。

8. 版本、CI 与许可

版本管理：构建版本号、兼容版本号、版本类型、git 提交号等由 cmake/version.cmake 统一管理（当前默认版本3.4.2.5.alpha，兼容版本3.0.0.0），并可通过BUILD_VER_NUMBER、BUILD_VER_COMPATIBLE、BUILD_VER_TYPE、BUILD_GITINFO等 CMake 变量覆盖。

CI 工作流：构建检查相关工作流在仓库 test/ci 下可找到对应脚本，例如pytest.sh（运行 Pytest 用例）、run.sh/run_case.sh（容器内用例执行）、cases.task（用例任务清单）、run_upgrade_compat.sh（升级兼容性检查）与win_cases.task/run_windows_ci.py（Windows 用例与 CI 执行）。

许可协议：TDengine 以 GNU Affero General Public License 3.0（AGPL-3.0）开源，核心模块包括集群功能与 AI Agent 均在该许可下可用。

至此，从环境准备、源码构建、选项调优、测试验证，到社区版打包、安装运行与覆盖率收集，一条完整的 TDengine 开发者工作流已全部打通。你可以基于 packaging/pack_community_tar.sh 的参数化设计定制自己的发布流程，也可以借助 test/cases 下的用例目录深入理解各功能模块的预期行为，为后续的代码贡献打好基础。

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